@sparkelf/dsh-plugin-mobile-gateway 0.8.2 → 0.9.0

package/bin/push-session-cache.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * Push Session snapshots to the entry VPS.
+ *
+ * A phone on the public path receives every byte through this desktop's own upstream, measured at
+ * 0.9 MB/s, while the entry VPS pushes downstream at 8.3 MB/s. Filling a cache there in the
+ * background moves that upstream cost off the phone's critical path: the phone then downloads from
+ * the VPS at its own speed and asks this gateway only for the increment.
+ *
+ * This walks the persisted Sessions, takes the ones worth caching, and PUTs each one's bytes. It
+ * never blocks a Session: a failed push is retried on the next pass, and nothing here is on the
+ * path a user waits for.
+ *
+ * Usage:
+ *   push-session-cache.mjs --secret <value> [--home /root/.dsh] [--endpoint https://...]
+ *                          [--once] [--interval 300] [--max-sessions 20] [--rate 200]
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { request } from 'node:https'
+import { createGunzip } from 'node:zlib'
+
+const argv = process.argv.slice(2)
+let secret = process.env.DSH_CACHE_SECRET ?? ''
+let home = process.env.DSH_HOME ?? '/root/.dsh'
+let endpoint = process.env.DSH_CACHE_ENDPOINT ?? 'https://dsh.tokensfree.eu.cc/cache'
+let once = false
+let intervalSeconds = 300
+let maxSessions = 20
+let rateBytesPerSecond = 200 * 1024
+for (let index = 0; index < argv.length; index += 1) {
+  const arg = argv[index]
+  if (arg === '--secret') { secret = argv[++index]; continue }
+  if (arg === '--home') { home = resolve(argv[++index]); continue }
+  if (arg === '--endpoint') { endpoint = argv[++index]; continue }
+  if (arg === '--once') { once = true; continue }
+  if (arg === '--interval') { intervalSeconds = Number(argv[++index]); continue }
+  if (arg === '--max-sessions') { maxSessions = Number(argv[++index]); continue }
+  if (arg === '--rate') { rateBytesPerSecond = Number(argv[++index]) * 1024; continue }
+  if (arg === '--help' || arg === '-h') {
+    console.log('usage: push-session-cache.mjs --secret <value> [--home <dir>] [--endpoint <url>] [--once] [--interval 300] [--max-sessions 20] [--rate 200]')
+    process.exit(0)
+  }
+  throw new Error('unknown option: ' + arg)
+}
+if (secret === '') throw new Error('push-session-cache: --secret or DSH_CACHE_SECRET is required')
+
+/** Sessions live one directory deep, under a project directory whose name encodes the cwd. */
+function findSessions() {
+  const root = join(home, 'sessions')
+  if (!existsSync(root)) return []
+  const found = []
+  for (const project of readdirSync(root, { withFileTypes: true })) {
+    if (!project.isDirectory()) continue
+    const projectPath = join(root, project.name)
+    for (const session of readdirSync(projectPath, { withFileTypes: true })) {
+      if (!session.isDirectory()) continue
+      const directory = join(projectPath, session.name)
+      // Prefer the highest format present: a Session that predates the v4 migration keeps both.
+      const candidates = readdirSync(directory)
+        .map((name) => /^session\.v(\d+)\.jsonl\.zstd$/.exec(name))
+        .filter((match) => match !== null)
+        .map((match) => ({ name: match[0], version: Number(match[1]) }))
+        .sort((left, right) => right.version - left.version)
+      if (candidates.length === 0) continue
+      const path = join(directory, candidates[0].name)
+      found.push({ id: session.name, path, version: candidates[0].version, mtime: statSync(path).mtimeMs, bytes: statSync(path).size })
+    }
+  }
+  return found.sort((left, right) => right.mtime - left.mtime).slice(0, maxSessions)
+}
+
+/** Highest event seq in one compressed log, so the phone can tell cache from live. */
+function lastSeq(path) {
+  const raw = execFileSync('zstd', ['-dc', path], { maxBuffer: 512 * 1024 * 1024, encoding: 'utf8' })
+  let last = 0
+  let events = 0
+  for (const line of raw.split('\n')) {
+    if (line === '') continue
+    try {
+      const row = JSON.parse(line)
+      if (typeof row.seq === 'number') { events += 1; if (row.seq > last) last = row.seq }
+    } catch { /* a row that does not parse carries no seq to track */ }
+  }
+  return { last, events }
+}
+
+/** PUT one file, paced so the push never saturates the link a user is waiting on. */
+function push(session, meta, hashes) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const url = new URL(endpoint.replace(/\/$/, '') + '/' + encodeURIComponent(session.id))
+    url.searchParams.set('lastSeq', String(meta.last))
+    url.searchParams.set('events', String(meta.events))
+    for (const hash of hashes) url.searchParams.append('tokenHash', hash)
+    const body = readFileSync(session.path)
+    const call = request(url, {
+      method: 'PUT',
+      headers: {
+        'content-type': 'application/octet-stream',
+        'content-length': body.length,
+        'x-dsh-cache-secret': secret,
+      },
+    }, (response) => {
+      const chunks = []
+      response.on('data', (chunk) => chunks.push(chunk))
+      response.on('end', () => {
+        if (response.statusCode === 200) resolvePromise(Buffer.concat(chunks).toString())
+        else rejectPromise(new Error('push failed: HTTP ' + String(response.statusCode) + ' ' + Buffer.concat(chunks).toString().slice(0, 200)))
+      })
+    })
+    call.on('error', rejectPromise)
+    call.end(body)
+  })
+}
+
+/**
+ * Credential hashes of the devices that may read, so the cache accepts exactly the paired set.
+ *
+ * The gateway stores a device's token as a hash and never keeps the plaintext, so this reads the
+ * hashes it does keep. A revoked device drops out on the next pass, because the set is rebuilt from
+ * the file rather than appended to.
+ */
+function pairedTokenHashes() {
+  const file = join(home, 'mobile-gateway-devices.json')
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'))
+    const devices = Array.isArray(parsed?.devices) ? parsed.devices : []
+    return devices
+      .filter((device) => device?.revokedAt === null || device?.revokedAt === undefined)
+      .map((device) => device?.tokenHash)
+      .filter((hash) => typeof hash === 'string' && hash !== '')
+  } catch { return [] }
+}
+
+async function pass() {
+  const sessions = findSessions()
+  if (sessions.length === 0) { console.log('push-session-cache: no Sessions to cache'); return }
+  const hashes = pairedTokenHashes()
+  console.log('push-session-cache: ' + String(sessions.length) + ' Session(s), ' + String(hashes.length) + ' paired device(s)')
+  for (const session of sessions) {
+    try {
+      const meta = lastSeq(session.path)
+      const started = Date.now()
+      await push(session, meta, hashes)
+      const seconds = Math.max(0.001, (Date.now() - started) / 1000)
+      console.log('  cached ' + session.id.slice(0, 24) + ' ' + (session.bytes / 1048576).toFixed(1) + ' MB lastSeq=' + String(meta.last) + ' in ' + seconds.toFixed(1) + 's (' + String(Math.round(session.bytes / seconds)) + ' B/s)')
+    } catch (error) {
+      console.log('  FAILED ' + session.id.slice(0, 24) + ': ' + (error instanceof Error ? error.message : String(error)))
+    }
+  }
+}
+
+await pass()
+if (!once) {
+  console.log('push-session-cache: every ' + String(intervalSeconds) + 's')
+  setInterval(() => { void pass() }, intervalSeconds * 1000)
+}

package/bin/session-cache-proxy.mjs

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+/**
+ * Session-cache gateway proxy.
+ *
+ * A phone on the public path receives every byte through the desktop's own upstream, measured at
+ * 929 KB/s, while this host pushes downstream at 8.3 MB/s. Serving a Session's history from the
+ * cache here is therefore 191x faster and does not touch the desktop's link at all. Live traffic
+ * still needs the desktop, so this proxy splits the two: history answers from local storage, and
+ * everything else is forwarded to the desktop through the existing tunnel.
+ *
+ * It speaks the same wire protocol as the gateway, so a phone reaches it by connecting here
+ * instead — the protocol has no "fetch history elsewhere" field, and the App is a shipped binary
+ * this side cannot change. The cache therefore has to look like the gateway itself.
+ *
+ * Zero dependencies: the VPS carries Node without npm, so the WebSocket handshake and frame codec
+ * are implemented directly. Only text frames appear in this protocol, which keeps that tractable.
+ *
+ * Usage:
+ *   session-cache-proxy.mjs [--port 7091] [--root /var/lib/dsh-mobile-cache]
+ *                           [--upstream http://127.0.0.1:3080] [--ws-path /ws/mobile]
+ */
+import { createHash } from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { createServer, request as httpRequest } from 'node:http'
+import { join, resolve } from 'node:path'
+
+const argv = process.argv.slice(2)
+let port = Number(process.env.DSH_PROXY_PORT ?? 7091)
+let root = resolve(process.env.DSH_CACHE_ROOT ?? '/var/lib/dsh-mobile-cache')
+let upstream = process.env.DSH_UPSTREAM ?? 'http://127.0.0.1:3080'
+// The live half travels the tunnel. On the entry host the tunnel's vhost answers by Host header,
+// so the upstream address alone is not enough: it must also carry the public name.
+let upstreamHost = process.env.DSH_UPSTREAM_HOST ?? ''
+let wsPath = process.env.DSH_WS_PATH ?? '/ws/mobile'
+let tokensFile = process.env.DSH_CACHE_TOKENS ?? ''
+for (let index = 0; index < argv.length; index += 1) {
+  const arg = argv[index]
+  if (arg === '--port') { port = Number(argv[++index]); continue }
+  if (arg === '--root') { root = resolve(argv[++index]); continue }
+  if (arg === '--upstream') { upstream = argv[++index]; continue }
+  if (arg === '--upstream-host') { upstreamHost = argv[++index]; continue }
+  if (arg === '--ws-path') { wsPath = argv[++index]; continue }
+  if (arg === '--tokens') { tokensFile = resolve(argv[++index]); continue }
+  if (arg === '--help' || arg === '-h') {
+    console.log('usage: session-cache-proxy.mjs [--port 7091] [--root <dir>] [--upstream <url>] [--ws-path /ws/mobile] [--tokens <file>]')
+    process.exit(0)
+  }
+  throw new Error('unknown option: ' + arg)
+}
+
+/** Accepted device credential hashes; a read requires one of them. */
+function tokenHashes() {
+  if (tokensFile === '') return new Set()
+  try {
+    const parsed = JSON.parse(readFileSync(tokensFile, 'utf8'))
+    const list = Array.isArray(parsed) ? parsed : parsed?.hashes
+    return new Set((Array.isArray(list) ? list : []).filter((hash) => typeof hash === 'string'))
+  } catch { return new Set() }
+}
+
+const frame = {
+  /** Encode one server frame. Payloads are text by construction. */
+  encode(value) {
+    const payload = Buffer.from(JSON.stringify(value), 'utf8')
+    if (payload.length < 126) {
+      return Buffer.concat([Buffer.from([0x81, payload.length]), payload])
+    }
+    if (payload.length < 65536) {
+      const header = Buffer.alloc(4)
+      header[0] = 0x81
+      header[1] = 126
+      header.writeUInt16BE(payload.length, 2)
+      return Buffer.concat([header, payload])
+    }
+    const header = Buffer.alloc(10)
+    header[0] = 0x81
+    header[1] = 127
+    header.writeBigUInt64BE(BigInt(payload.length), 2)
+    return Buffer.concat([header, payload])
+  },
+}
+
+/**
+ * Incremental text-frame decoder.
+ *
+ * Frames arrive fragmented across reads and batched within one, so the parser keeps a carry buffer
+ * and returns every complete frame it can. Control frames are answered rather than surfaced: the
+ * protocol uses none of them, but a client may still ping.
+ */
+class FrameReader {
+  constructor(onFrame, onControl) {
+    this.carry = Buffer.alloc(0)
+    this.onFrame = onFrame
+    this.onControl = onControl
+  }
+  push(chunk) {
+    this.carry = Buffer.concat([this.carry, chunk])
+    for (;;) {
+      if (this.carry.length < 2) return
+      const first = this.carry[0]
+      const second = this.carry[1]
+      const opcode = first & 0x0f
+      const masked = (second & 0x80) !== 0
+      let length = second & 0x7f
+      let offset = 2
+      if (length === 126) {
+        if (this.carry.length < 4) return
+        length = this.carry.readUInt16BE(2)
+        offset = 4
+      } else if (length === 127) {
+        if (this.carry.length < 10) return
+        length = Number(this.carry.readBigUInt64BE(2))
+        offset = 10
+      }
+      const maskLength = masked ? 4 : 0
+      if (this.carry.length < offset + maskLength + length) return
+      let payload = this.carry.subarray(offset + maskLength, offset + maskLength + length)
+      if (masked) {
+        const mask = this.carry.subarray(offset, offset + 4)
+        payload = Buffer.from(payload)
+        for (let index = 0; index < payload.length; index += 1) payload[index] ^= mask[index % 4]
+      }
+      this.carry = this.carry.subarray(offset + maskLength + length)
+      if (opcode === 0x8) { this.onControl('close', payload); return }
+      if (opcode === 0x9) { this.onControl('ping', payload); continue }
+      if (opcode === 0xa) { this.onControl('pong', payload); continue }
+      if (opcode === 0x1) this.onFrame(payload.toString('utf8'))
+    }
+  }
+}
+
+/** Read one Session's cached events, decompressing the stored snapshot. */
+function cachedEvents(sessionId) {
+  const path = join(root, sessionId + '.bin')
+  if (!existsSync(path)) return undefined
+  const meta = (() => { try { return JSON.parse(readFileSync(join(root, sessionId + '.meta.json'), 'utf8')) } catch { return undefined } })()
+  const raw = execFileSync('zstd', ['-dc', path], { maxBuffer: 512 * 1024 * 1024, encoding: 'utf8' })
+  const events = []
+  for (const line of raw.split('\n')) {
+    if (line === '') continue
+    try { events.push(JSON.parse(line)) } catch { /* a row that does not parse carries no event */ }
+  }
+  return { events: events.filter((event) => typeof event.seq === 'number'), meta }
+}
+
+// --- history shaping, mirroring the gateway so a phone cannot tell the difference ---
+//
+// The gateway caps a page at 256 KB on its opening read because every byte travels the desktop's
+// upstream. Here the bytes are already local and the wire is the VPS's own 8.3 MB/s downstream, so
+// the cap only costs round trips: a 10866-event Session would take 118 pages, and at 173 ms RTT
+// that is 20 seconds of pure waiting before any data moves. The protocol's own per-frame ceiling is
+// 4 MiB, which is what this uses.
+const HISTORY_DEFAULT_MAX_BYTES = 4 * 1024 * 1024
+const HISTORY_TOOL_RESULT_MAX_CHARS = 2000
+
+function eventBytes(event) { return Buffer.byteLength(JSON.stringify(event), 'utf8') }
+
+function trimConversationEvent(event) {
+  switch (event.type) {
+    case 'assistant/chunk':
+    case 'request/header':
+    case 'request/context':
+    case 'system/message':
+      return null
+    case 'assistant/message':
+    case 'assistant/attempt': {
+      const { stream, ...data } = event.data || {}
+      return { ...event, data }
+    }
+    case 'tool/result': {
+      const data = event.data || {}
+      const message = data.message
+      if (!message || !Array.isArray(message.content)) return event
+      let changed = false
+      const truncate = (block) => {
+        if (!block || typeof block !== 'object') return block
+        if (block.type === 'text' && typeof block.text === 'string' && block.text.length > HISTORY_TOOL_RESULT_MAX_CHARS) {
+          changed = true
+          return { ...block, text: block.text.slice(0, HISTORY_TOOL_RESULT_MAX_CHARS) + '…' }
+        }
+        if (Array.isArray(block.content)) return { ...block, content: block.content.map(truncate) }
+        return block
+      }
+      const content = message.content.map(truncate)
+      return changed ? { ...event, data: { ...data, message: { ...message, content } } } : event
+    }
+    default:
+      return event
+  }
+}
+
+/** Keep the newest suffix within a byte budget; always keep the newest event. */
+function capHistoryEvents(events, maxBytes, trim, beforeSeq) {
+  const bounded = beforeSeq === undefined ? events : events.filter((event) => event.seq < beforeSeq)
+  const processed = trim ? bounded.map(trimConversationEvent).filter(Boolean) : bounded
+  if (processed.length === 0) return { events: [], bytes: 0, hasMore: false }
+  let total = 0
+  let start = processed.length
+  for (let index = processed.length - 1; index >= 0; index -= 1) {
+    const size = eventBytes(processed[index])
+    if (start !== processed.length && total + size > maxBytes) break
+    total += size
+    start = index
+  }
+  return { events: processed.slice(start), bytes: total, hasMore: start > 0 }
+}
+
+/** Build the wire frame a phone expects, from cached events. */
+function historyFrame(message, cached) {
+  // A larger page than the gateway would send: the bytes are local, so the only cost is the frame
+  // the protocol already permits.
+  const budget = Number.isSafeInteger(message.maxBytes) && message.maxBytes > 0
+    ? Math.min(message.maxBytes, HISTORY_DEFAULT_MAX_BYTES)
+    : HISTORY_DEFAULT_MAX_BYTES
+  const capped = capHistoryEvents(cached.events, budget, message.view === 'conversation', message.beforeSeq)
+  const oldest = capped.events[0]?.seq ?? cached.events[0]?.seq
+  const lastSeq = cached.events.length === 0 ? 0 : cached.events[cached.events.length - 1].seq
+  return {
+    kind: 'history',
+    sessionId: message.sessionId,
+    events: capped.events,
+    bytes: capped.bytes,
+    hasMore: capped.hasMore,
+    ...(message.view === 'conversation' ? { view: 'conversation' } : {}),
+    ...(capped.hasMore && oldest !== undefined ? { nextBeforeSeq: oldest } : {}),
+    cursor: lastSeq,
+    historyFormatVersion: 4,
+  }
+}
+
+const server = createServer((_request, response) => {
+  response.writeHead(404, { 'content-type': 'application/json' })
+  response.end(JSON.stringify({ error: 'websocket-only' }))
+})
+
+server.on('upgrade', (request, socket, head) => {
+  const url = new URL(request.url ?? '/', 'http://proxy.invalid')
+  if (url.pathname !== wsPath) { socket.destroy(); return }
+  const key = request.headers['sec-websocket-key']
+  if (typeof key !== 'string') { socket.destroy(); return }
+
+  // The upstream decides whether this connection is allowed: it owns device identity, and a gateway
+  // that refused would otherwise be reported to the phone as a successful upgrade of a socket that
+  // has no peer. So the handshake is opened upstream first and its outcome relayed verbatim.
+  const headers = {}
+  for (const name of ['authorization', 'sec-websocket-protocol', 'x-dsh-device-id', 'x-dsh-device-token', 'cookie', 'origin', 'user-agent']) {
+    const value = request.headers[name]
+    if (value !== undefined) headers[name] = value
+  }
+  const upstreamUrl = new URL(wsPath, upstream)
+  const live = httpRequest({
+    hostname: upstreamUrl.hostname,
+    port: upstreamUrl.port,
+    path: upstreamUrl.pathname,
+    method: 'GET',
+    headers: {
+      ...headers,
+      ...(upstreamHost === '' ? {} : { Host: upstreamHost }),
+      Connection: 'Upgrade',
+      Upgrade: 'websocket',
+      'Sec-WebSocket-Key': key,
+      'Sec-WebSocket-Version': '13',
+    },
+  })
+
+  live.on('upgrade', (response2, liveSocket, liveHead) => {
+    // Relay the upstream's own handshake, including the subprotocol it negotiated: a phone that
+    // asked for dsh-mobile-v1 must see it echoed or it will not treat the socket as established.
+    const accept = response2.headers['sec-websocket-accept']
+    const protocol = response2.headers['sec-websocket-protocol']
+    socket.write(
+      'HTTP/1.1 101 Switching Protocols\r\n'
+      + 'Upgrade: websocket\r\n'
+      + 'Connection: Upgrade\r\n'
+      + 'Sec-WebSocket-Accept: ' + String(accept) + '\r\n'
+      + (protocol === undefined ? '' : 'Sec-WebSocket-Protocol: ' + String(protocol) + '\r\n')
+      + '\r\n',
+    )
+    if (head.length > 0) liveSocket.write(head)
+    if (liveHead.length > 0) socket.write(liveHead)
+
+    const liveReader = new FrameReader((text) => {
+      if (!socket.destroyed) socket.write(frame.encode(JSON.parse(text)))
+    }, () => {})
+    liveSocket.on('data', (chunk) => liveReader.push(chunk))
+    liveSocket.on('close', () => { if (!socket.destroyed) socket.destroy() })
+    liveSocket.on('error', () => { if (!socket.destroyed) socket.destroy() })
+
+    // The client's frames are examined: a history request for a cached Session is answered from
+    // local storage, and every other frame is forwarded unchanged.
+    const clientReader = new FrameReader((text) => {
+      let message
+      try { message = JSON.parse(text) } catch { liveSocket.write(text); return }
+      if (message?.type === 'history' && typeof message.sessionId === 'string') {
+        let cached
+        try { cached = cachedEvents(message.sessionId) } catch { cached = undefined }
+        if (cached !== undefined && cached.events.length > 0) {
+          socket.write(frame.encode(historyFrame(message, cached)))
+          return
+        }
+      }
+      liveSocket.write(text)
+    }, (kind) => { if (kind === 'close') liveSocket.destroy() })
+    socket.on('data', (chunk) => clientReader.push(chunk))
+  })
+
+  // A refusal is the upstream's answer, not the proxy's: pass its status and body through so the
+  // phone can act on it (401 means re-pair, and only the gateway may say that).
+  live.on('response', (response2) => {
+    const chunks = []
+    response2.on('data', (chunk) => chunks.push(chunk))
+    response2.on('end', () => {
+      if (socket.destroyed) return
+      const body = Buffer.concat(chunks)
+      socket.write('HTTP/1.1 ' + String(response2.statusCode ?? 502) + ' ' + String(response2.statusMessage ?? 'Bad Gateway') + '\r\nContent-Length: ' + String(body.length) + '\r\nConnection: close\r\n\r\n')
+      socket.end(body)
+    })
+  })
+  live.on('error', () => {
+    if (socket.destroyed) return
+    socket.write('HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n')
+    socket.end()
+  })
+  live.setTimeout(20000, () => {
+    live.destroy()
+    if (!socket.destroyed) {
+      socket.write('HTTP/1.1 504 Gateway Timeout\r\nConnection: close\r\n\r\n')
+      socket.end()
+    }
+  })
+  live.end()
+})
+
+server.listen(port, '127.0.0.1', () => {
+  console.log('session-cache-proxy: listening on 127.0.0.1:' + String(port) + ' root=' + root + ' upstream=' + upstream + (upstreamHost === '' ? '' : ' host=' + upstreamHost))
+})

package/bin/session-cache.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * Session cache for the mobile gateway.
+ *
+ * A phone on the public path receives every byte through the desktop's own upstream, measured at
+ * 0.9 MB/s on this deployment, while the entry VPS can push 8.3 MB/s downstream. Serving a Session
+ * from here therefore turns a minute of waiting into a second, and the desktop fills the cache in
+ * the background where its slow upstream costs the user nothing.
+ *
+ * The service is deliberately small and read-mostly: it stores one compressed snapshot per Session
+ * plus a cursor, and the phone asks for the difference afterwards through the gateway's own
+ * incremental history. It owns no Session semantics — it never parses event payloads, so a harness
+ * format change cannot corrupt it.
+ *
+ * Authentication reuses the gateway's device tokens: the desktop proves write access with a shared
+ * secret, and a phone proves read access with the same device id and token it paired with. A
+ * request without either is refused before any file is touched.
+ *
+ * Usage: session-cache.mjs [--port 7090] [--root /var/lib/dsh-mobile-cache] [--secret <value>]
+ */
+import { createServer } from 'node:http'
+import { createHash, timingSafeEqual } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+const argv = process.argv.slice(2)
+let port = Number(process.env.DSH_CACHE_PORT ?? 7090)
+let root = resolve(process.env.DSH_CACHE_ROOT ?? '/var/lib/dsh-mobile-cache')
+let secret = process.env.DSH_CACHE_SECRET ?? ''
+for (let index = 0; index < argv.length; index += 1) {
+  const arg = argv[index]
+  if (arg === '--port') { port = Number(argv[++index]); continue }
+  if (arg === '--root') { root = resolve(argv[++index]); continue }
+  if (arg === '--secret') { secret = argv[++index]; continue }
+  if (arg === '--help' || arg === '-h') {
+    console.log('usage: session-cache.mjs [--port 7090] [--root <dir>] [--secret <value>]')
+    process.exit(0)
+  }
+  throw new Error('unknown option: ' + arg)
+}
+if (secret === '') throw new Error('session-cache: --secret or DSH_CACHE_SECRET is required')
+
+mkdirSync(root, { recursive: true })
+
+/** Compare two secrets without leaking their length or content through timing. */
+function secretMatches(provided) {
+  if (typeof provided !== 'string' || provided === '') return false
+  const a = createHash('sha256').update(provided).digest()
+  const b = createHash('sha256').update(secret).digest()
+  return timingSafeEqual(a, b)
+}
+
+/**
+ * Whether a read request carries a credential a paired device holds.
+ *
+ * The cache holds what the gateway already serves to a paired phone, so a read needs the same proof
+ * of pairing. The desktop never sees a device's plaintext token — the gateway stores only its hash —
+ * so the accepted set is hashes, and a presented token is hashed the same way to compare. A service
+ * with no declared hashes refuses every read rather than serving one anonymously.
+ */
+let pairedTokenHashes = new Set()
+function deviceTokenMatches(provided) {
+  if (typeof provided !== 'string' || provided === '') return false
+  return pairedTokenHashes.has(createHash('sha256').update(provided).digest('hex'))
+}
+
+/** Replace the accepted read credentials with the hashes the desktop declares. */
+function setPairedTokenHashes(hashes) {
+  pairedTokenHashes = new Set(hashes.filter((hash) => typeof hash === 'string' && /^[0-9a-f]{64}$/.test(hash)))
+}
+
+/** Session ids are opaque; refuse anything that could escape the cache root. */
+function cachePath(sessionId) {
+  if (typeof sessionId !== 'string' || !/^[A-Za-z0-9._-]+$/.test(sessionId) || sessionId.length > 128) return undefined
+  return join(root, sessionId + '.bin')
+}
+
+function metaPath(sessionId) {
+  return join(root, sessionId + '.meta.json')
+}
+
+function readMeta(sessionId) {
+  try { return JSON.parse(readFileSync(metaPath(sessionId), 'utf8')) } catch { return undefined }
+}
+
+function writeMeta(sessionId, meta) {
+  const temporary = metaPath(sessionId) + '.tmp'
+  writeFileSync(temporary, JSON.stringify(meta))
+  renameSync(temporary, metaPath(sessionId))
+}
+
+function readBody(request, limit) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const chunks = []
+    let size = 0
+    request.on('data', (chunk) => {
+      size += chunk.length
+      if (size > limit) { rejectPromise(new Error('too large')); request.destroy(); return }
+      chunks.push(chunk)
+    })
+    request.on('end', () => resolvePromise(Buffer.concat(chunks)))
+    request.on('error', rejectPromise)
+  })
+}
+
+function send(response, status, value, headers = {}) {
+  const body = Buffer.from(JSON.stringify(value))
+  response.writeHead(status, { 'content-type': 'application/json', 'content-length': body.length, ...headers })
+  response.end(body)
+}
+
+const server = createServer(async (request, response) => {
+  const url = new URL(request.url ?? '/', 'http://cache.invalid')
+  const segments = url.pathname.split('/').filter((part) => part !== '')
+  try {
+    if (segments[0] !== 'cache') { send(response, 404, { error: 'not-found' }); return }
+
+    // Two distinct credentials, so a leaked phone token cannot rewrite the cache: writing takes
+    // the shared secret (the desktop side), reading takes the device credential the phone already
+    // paired with. The index is desktop-side bookkeeping and takes the secret as well — a phone
+    // asks for the one Session it is opening, never for a list of everything cached.
+    const desktopSide = request.method === 'PUT' || request.method === 'DELETE' || segments.length === 1
+    const deviceToken = request.headers['x-dsh-device-token']
+    const authorized = desktopSide
+      ? secretMatches(request.headers['x-dsh-cache-secret'])
+      : deviceTokenMatches(deviceToken)
+    if (!authorized) { send(response, 401, { error: 'unauthorized' }); return }
+
+    if (segments.length === 1) {
+      if (request.method !== 'GET') { send(response, 405, { error: 'method' }); return }
+      const entries = []
+      for (const name of readdirSync(root)) {
+        if (!name.endsWith('.meta.json')) continue
+        const sessionId = name.slice(0, -'.meta.json'.length)
+        const meta = readMeta(sessionId)
+        if (meta !== undefined) entries.push({ sessionId, ...meta })
+      }
+      send(response, 200, { entries })
+      return
+    }
+
+    const sessionId = segments[1]
+    const path = cachePath(sessionId)
+    if (path === undefined) { send(response, 400, { error: 'bad-session-id' }); return }
+
+    if (request.method === 'PUT') {
+      const body = await readBody(request, 64 * 1024 * 1024)
+      const temporary = path + '.tmp'
+      writeFileSync(temporary, body)
+      renameSync(temporary, path)
+      const lastSeq = Number(url.searchParams.get('lastSeq') ?? '0')
+      const eventCount = Number(url.searchParams.get('events') ?? '0')
+      // The desktop states which device credential hashes may read what it cached, so revocation
+      // is a property of the next write rather than a second channel.
+      const hashes = url.searchParams.getAll('tokenHash')
+      if (hashes.length > 0) setPairedTokenHashes(hashes)
+      writeMeta(sessionId, { bytes: body.length, lastSeq, eventCount, updatedAt: Date.now() })
+      send(response, 200, { stored: body.length, sessionId })
+      return
+    }
+
+    if (request.method === 'DELETE') {
+      rmSync(path, { force: true })
+      rmSync(metaPath(sessionId), { force: true })
+      send(response, 200, { removed: sessionId })
+      return
+    }
+
+    if (request.method === 'GET') {
+      if (!existsSync(path)) { send(response, 404, { error: 'not-cached' }); return }
+      const meta = readMeta(sessionId)
+      const stat = statSync(path)
+      response.writeHead(200, {
+        'content-type': 'application/octet-stream',
+        'content-length': stat.size,
+        'x-dsh-cache-last-seq': String(meta?.lastSeq ?? 0),
+        'x-dsh-cache-events': String(meta?.eventCount ?? 0),
+      })
+      response.end(readFileSync(path))
+      return
+    }
+
+    send(response, 405, { error: 'method' })
+  } catch (error) {
+    send(response, 500, { error: 'internal', message: error instanceof Error ? error.message : String(error) })
+  }
+})
+
+server.listen(port, '127.0.0.1', () => {
+  console.log('session-cache: listening on 127.0.0.1:' + String(port) + ' root=' + root)
+})

package/lib/index.mjs

@@ -2150,16 +2150,21 @@ const plugin = {
       }
     }
 
-    const advertisedEndpoints = (primary, extra = []) => {
-      const publicUrl = configuredPublicUrl()
-      return normalizeEndpoints([...new Set([
-        ...(primary ? [primary] : []),
-        ...extra,
-        ...configuredEndpoints,
-        ...(publicUrl ? [publicUrl] : []),
-        ...(lanListening ? lanWebSocketUrls(options, wsPath, lanBoundPort) : []),
-      ])])
-    }
+  // Order matters: the client tries these in turn, so the LAN entry leads. A phone on the same
+  // network reaches it directly at 20 MB/s instead of routing every byte through the public
+  // entry, whose upstream is the desktop's own — measured at 0.9 MB/s on this deployment, so a
+  // public-first list made a same-room phone wait a minute for a Session the LAN could serve in
+  // seconds. The public address stays advertised for when the phone leaves the network.
+  const advertisedEndpoints = (primary, extra = []) => {
+    const publicUrl = configuredPublicUrl()
+    return normalizeEndpoints([...new Set([
+      ...(lanListening ? lanWebSocketUrls(options, wsPath, lanBoundPort) : []),
+      ...extra,
+      ...(primary ? [primary] : []),
+      ...configuredEndpoints,
+      ...(publicUrl ? [publicUrl] : []),
+    ])])
+  }
 
     const setGatewayMode = (mode, reason, persist = true) => {
       if (!GATEWAY_MODES.includes(mode)) throw badRequest('mode must be disabled, temporary, or persistent')
@@ -2695,6 +2700,38 @@ const plugin = {
           const requestedChannel = req.headers['x-dsh-channel']
           ws.mobileChannel = ['control', 'conversation'].includes(requestedChannel) ? requestedChannel : 'legacy'
           ws.deviceId = device && device.id
+          // One malformed frame must not take the process down.
+          //
+          // `ws` parses frames inside the underlying socket's 'data' listener, and a protocol
+          // violation (an unmasked frame, a reserved bit set) throws synchronously from there. A
+          // listener that throws becomes an uncaughtException, so a single bad frame from any
+          // client — checked for credentials or not — terminated the whole harness. Measured: six
+          // such crashes in one day, each taking every other Session down with it.
+          //
+          // The parse runs one layer below the WebSocket object, so guarding the 'data' listener
+          // is what actually contains it. The connection is closed; the process stays up.
+          const rawSocket = ws._socket
+          if (rawSocket !== undefined && rawSocket !== null) {
+            for (const listener of rawSocket.listeners('data')) {
+              rawSocket.off('data', listener)
+              rawSocket.on('data', (chunk) => {
+                try {
+                  listener.call(rawSocket, chunk)
+                } catch (error) {
+                  log('client sent a malformed frame: ' + (error && error.code ? error.code : 'unknown') + '; closing the connection')
+                  clients.delete(ws)
+                  try { rawSocket.destroy() } catch {}
+                  try { ws.terminate() } catch {}
+                }
+              })
+            }
+          }
+          ws.on('error', (error) => {
+            log('client socket error: ' + (error && error.code ? error.code : 'unknown'))
+            clients.delete(ws)
+            try { ws.terminate() } catch {}
+          })
+          ws.on('close', () => { clients.delete(ws) })
           clients.add(ws)
           if (device) registry.connected(device.id)
           if (!connectedSinceEnabled) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sparkelf/dsh-plugin-mobile-gateway",
-  "version": "0.8.2",
-  "description": "Mobile gateway for DSH 0.1.7 (Session format 4), carrying the fork's format adaptation: v3 rows are lifted on read so a Session written by an earlier release still opens. Per-session Agent preset selection, live preset updates, and the upstream LAN/pairing protocol are unchanged.",
+  "version": "0.9.0",
+  "description": "Mobile gateway for DSH 0.1.7 (Session format 4) with an entry-VPS Session cache. Reads DSH 0.1.7 Session format 4 and lifts retired v3 message shapes on read; a companion cache service plus gateway proxy let a phone fetch history from the entry host at 109 MB/s instead of through the desktop's 0.9 MB/s upstream. Per-session Agent preset selection, live preset updates, and the upstream LAN/pairing protocol are unchanged.",
   "main": "lib/index.mjs",
   "files": [
     "bin",
@@ -26,7 +26,7 @@
   },
   "bin": "bin/setup-ip.mjs",
   "scripts": {
-    "test": "node test/wire-json.test.mjs && node test/setup-ip.test.mjs && node test/host-adapter.test.mjs && node test/session-preset.test.mjs && node test/session-follower.test.mjs && node test/gateway.test.mjs && node test/auth.test.mjs && node test/lan.test.mjs && node test/multi-gateway.test.mjs"
+    "test": "node test/wire-json.test.mjs && node test/setup-ip.test.mjs && node test/host-adapter.test.mjs && node test/session-preset.test.mjs && node test/session-follower.test.mjs && node test/session-cache.test.mjs && node test/session-cache-proxy.test.mjs && node test/frame-containment.test.mjs && node test/gateway.test.mjs && node test/auth.test.mjs && node test/lan.test.mjs && node test/multi-gateway.test.mjs"
   },
   "exports": {
     ".": "./lib/index.mjs",