dsh-remote-control-plugin 0.3.5 → 0.4.0

package/host/handshake.js

@@ -0,0 +1,39 @@
+import { signPayload, verifyPayload } from './identity.js'
+
+/**
+ * Pairing handshake messages for forward secrecy.
+ *
+ * Each side mints a fresh X25519 ephemeral key for one pairing attempt and
+ * signs the public half together with the device id and the invite nonce:
+ *
+ *   payload = `${deviceId}\n${pairCode}\n${ephemeralPublicPem}`
+ *
+ * The signature proves the ephemeral belongs to the identity that was approved,
+ * so a relay cannot substitute its own ephemeral key. The private half never
+ * leaves the process and is dropped once both lanes are derived.
+ *
+ * This is a message format, not a protocol: ordering and retry live in hello.
+ */
+
+export function ephemeralPayload(deviceId, pairCode, publicPem) {
+  return `${deviceId}\n${pairCode}\n${publicPem}`
+}
+
+export function mintEphemeral(identity, deviceId, pairCode, keypair) {
+  const publicPem = keypair.publicKey.export({ type: 'spki', format: 'pem' })
+  return {
+    publicPem,
+    signature: signPayload(identity.ed25519.privateKey, ephemeralPayload(deviceId, pairCode, publicPem)),
+  }
+}
+
+export function verifyEphemeral(identityPublicKeyPem, deviceId, pairCode, message) {
+  if (!identityPublicKeyPem || !message || typeof message.publicPem !== 'string' || typeof message.signature !== 'string') {
+    return false
+  }
+  return verifyPayload(
+    identityPublicKeyPem,
+    ephemeralPayload(deviceId, pairCode, message.publicPem),
+    message.signature,
+  )
+}

package/host/identity.js

@@ -0,0 +1,112 @@
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from 'node:crypto'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+/**
+ * Device identity: one Ed25519 signing key and one X25519 key-agreement key per
+ * install, generated once and persisted owner-only.
+ *
+ * The Ed25519 key is the device's long-term identity: its fingerprint goes into
+ * invites and approval records, and peer calls are signed with it. The X25519
+ * key is reserved for the encrypted channel (phase A2); it is stored now so a
+ * device never has to rotate identity to gain encryption.
+ *
+ * The short authentication string (SAS) binds two fingerprints and the invite
+ * nonce, so both screens show the same six digits only when both devices hold
+ * the keys they claim.
+ */
+
+export function fingerprintOf(publicKeyPem) {
+  const key = createPublicKey(publicKeyPem)
+  const der = key.export({ type: 'spki', format: 'der' })
+  return createHash('sha256').update(der).digest('hex').slice(0, 32)
+}
+
+export function sasCode(fingerprintA, fingerprintB, nonce) {
+  const ordered = [fingerprintA, fingerprintB].sort().join(':')
+  const digest = createHash('sha256').update(`${ordered}:${nonce}`).digest()
+  const value = digest.readUInt32BE(0) % 1_000_000
+  return String(value).padStart(6, '0')
+}
+
+export function signPayload(privateKey, payload) {
+  return sign(null, Buffer.from(payload), privateKey).toString('base64url')
+}
+
+export function verifyPayload(publicKeyPem, payload, signature) {
+  try {
+    return verify(null, Buffer.from(payload), createPublicKey(publicKeyPem), Buffer.from(signature, 'base64url'))
+  } catch {
+    return false
+  }
+}
+
+export async function loadOrCreateIdentity(file, log = console, store) {
+  let stored
+  if (store) {
+    try {
+      stored = await store.load()
+    } catch (error) {
+      log.warn?.(`[remote-control] could not read the identity record: ${error?.message || error}`)
+    }
+  }
+  if (!stored) {
+    try {
+      stored = JSON.parse(await readFile(file, 'utf8'))
+    } catch (error) {
+      if (error?.code !== 'ENOENT') log.warn?.(`[remote-control] could not read identity: ${error?.message || error}`)
+    }
+  }
+
+  if (stored?.ed25519?.privateKey && stored?.ed25519?.publicKey) {
+    try {
+      const ed25519 = {
+        publicKey: createPublicKey(stored.ed25519.publicKey),
+        privateKey: createPrivateKey(stored.ed25519.privateKey),
+        publicKeyPem: stored.ed25519.publicKey,
+      }
+      let x25519 = null
+      if (stored?.x25519?.privateKey) {
+        x25519 = {
+          publicKey: createPublicKey(stored.x25519.publicKey),
+          privateKey: createPrivateKey(stored.x25519.privateKey),
+          publicKeyPem: stored.x25519.publicKey,
+        }
+      }
+      return { ed25519, x25519, fingerprint: fingerprintOf(ed25519.publicKeyPem), createdAt: stored.createdAt ?? Date.now(), fresh: false }
+    } catch {
+      log.warn?.('[remote-control] stored identity is unusable; generating a new one')
+    }
+  }
+
+  const ed = generateKeyPairSync('ed25519')
+  const x = generateKeyPairSync('x25519')
+  const record = {
+    createdAt: Date.now(),
+    ed25519: {
+      publicKey: ed.publicKey.export({ type: 'spki', format: 'pem' }),
+      privateKey: ed.privateKey.export({ type: 'pkcs8', format: 'pem' }),
+    },
+    x25519: {
+      publicKey: x.publicKey.export({ type: 'spki', format: 'pem' }),
+      privateKey: x.privateKey.export({ type: 'pkcs8', format: 'pem' }),
+    },
+  }
+  try {
+    if (store) {
+      await store.save(record)
+    } else {
+      await mkdir(path.dirname(file), { recursive: true })
+      await writeFile(file, JSON.stringify(record, null, 2), { mode: 0o600 })
+    }
+  } catch (error) {
+    log.warn?.(`[remote-control] could not persist identity: ${error?.message || error}`)
+  }
+  return {
+    ed25519: { publicKey: ed.publicKey, privateKey: ed.privateKey, publicKeyPem: record.ed25519.publicKey },
+    x25519: { publicKey: x.publicKey, privateKey: x.privateKey, publicKeyPem: record.x25519.publicKey },
+    fingerprint: fingerprintOf(record.ed25519.publicKey),
+    createdAt: record.createdAt,
+    fresh: true,
+  }
+}

package/host/lane.js

@@ -0,0 +1,10 @@
+/**
+ * Lane preference: a same-LAN peer always wins, then a punched P2P path, then
+ * the relay. Kept pure so the ordering is testable without any network.
+ */
+export function selectLane({ sameLan = false, punched = false, relayAvailable = false } = {}) {
+  if (sameLan) return 'lan'
+  if (punched) return 'p2p'
+  if (relayAvailable) return 'relay'
+  return 'none'
+}

package/host/nat.js

@@ -0,0 +1,113 @@
+import dgram from 'node:dgram'
+import { randomBytes } from 'node:crypto'
+import os from 'node:os'
+
+/**
+ * Phase B building blocks: IPv6-first candidate discovery and a minimal STUN
+ * binding client.
+ *
+ * Only this half is verifiable on the current network (which has no IPv6 and no
+ * second NAT): the binding request/response codec and candidate filtering are
+ * exercised against an in-process STUN responder. Hole punching itself needs
+ * two real NATs and is not attempted here.
+ */
+
+const MAGIC = 0x2112a442
+const BINDING_REQUEST = 0x0001
+const BINDING_SUCCESS = 0x0101
+const XOR_MAPPED_ADDRESS = 0x0020
+
+export function buildBindingRequest(transactionId = randomBytes(12)) {
+  const buffer = Buffer.alloc(20)
+  buffer.writeUInt16BE(BINDING_REQUEST, 0)
+  buffer.writeUInt16BE(0, 2)
+  buffer.writeUInt32BE(MAGIC, 4)
+  transactionId.copy(buffer, 8, 0, 12)
+  return buffer
+}
+
+export function parseBindingResponse(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 20) return undefined
+  if (buffer.readUInt16BE(0) !== BINDING_SUCCESS) return undefined
+  if (buffer.readUInt32BE(4) !== MAGIC) return undefined
+  const length = buffer.readUInt16BE(2)
+  if (20 + length > buffer.length) return undefined
+  let offset = 20
+  const end = 20 + length
+  while (offset + 4 <= end) {
+    const type = buffer.readUInt16BE(offset)
+    const size = buffer.readUInt16BE(offset + 2)
+    const valueStart = offset + 4
+    if (valueStart + size > end) return undefined
+    if (type === XOR_MAPPED_ADDRESS && size >= 8) {
+      const family = buffer[valueStart + 1]
+      const port = buffer.readUInt16BE(valueStart + 2) ^ (MAGIC >>> 16)
+      if (family === 0x01) {
+        const raw = buffer.readUInt32BE(valueStart + 4)
+        const address = (raw ^ MAGIC) >>> 0
+        return {
+          family: 'IPv4',
+          address: `${(address >>> 24) & 0xff}.${(address >>> 16) & 0xff}.${(address >>> 8) & 0xff}.${address & 0xff}`,
+          port,
+        }
+      }
+      if (family === 0x02 && size >= 20) {
+        const raw = buffer.subarray(valueStart + 4, valueStart + 20)
+        const mask = Buffer.alloc(16)
+        mask.writeUInt32BE(MAGIC, 0)
+        buffer.copy(mask, 4, 4, 20) // transaction id
+        const address = Buffer.from(raw.map((byte, index) => byte ^ mask[index]))
+        const groups = []
+        for (let i = 0; i < 16; i += 2) groups.push(address.readUInt16BE(i).toString(16))
+        return { family: 'IPv6', address: groups.join(':'), port }
+      }
+    }
+    offset = valueStart + size + ((4 - (size % 4)) % 4)
+  }
+  return undefined
+}
+
+export function stunBinding({ host = 'stun.l.google.com', port = 19302, timeoutMs = 2000 } = {}) {
+  return new Promise((resolve) => {
+    const transactionId = randomBytes(12)
+    const request = buildBindingRequest(transactionId)
+    const socket = dgram.createSocket('udp4')
+    let settled = false
+    const finish = (value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      try { socket.close() } catch { /* ignore */ }
+      resolve(value)
+    }
+    const timer = setTimeout(() => finish(undefined), timeoutMs)
+    socket.on('error', () => finish(undefined))
+    socket.on('message', (message) => {
+      if (message.length >= 20 && message.readUInt32BE(4) === MAGIC && message.subarray(8, 20).equals(transactionId)) {
+        finish(parseBindingResponse(message))
+      }
+    })
+    socket.send(request, 0, request.length, port, host, (error) => {
+      if (error) finish(undefined)
+    })
+  })
+}
+
+/** IPv6 candidates first, then IPv4; loopback and link-local are excluded. */
+export function localCandidates(interfaces = os.networkInterfaces()) {
+  const ipv6 = []
+  const ipv4 = []
+  for (const entries of Object.values(interfaces ?? {})) {
+    for (const entry of entries ?? []) {
+      if (!entry || entry.internal) continue
+      if (entry.family === 'IPv6' || entry.family === 6) {
+        if (entry.address.startsWith('fe80') || entry.address === '::1') continue
+        ipv6.push({ family: 'IPv6', address: entry.address })
+      } else if (entry.family === 'IPv4' || entry.family === 4) {
+        if (entry.address.startsWith('127.')) continue
+        ipv4.push({ family: 'IPv4', address: entry.address })
+      }
+    }
+  }
+  return [...ipv6, ...ipv4]
+}

package/host/p2p.js

@@ -0,0 +1,169 @@
+import http from 'node:http'
+import { createBoxCipher } from './crypto.js'
+import { createUdpChannel } from './udp-channel.js'
+
+/**
+ * P2P proxy for the punched lane: carries HTTP-shaped peer calls and SSE frames
+ * over the UDP channel between two DSH instances and replays them into the
+ * local listener, so authentication, sealing and scope checks stay in one place.
+ *
+ * Unary calls use request/response (ACKed). Stream frames are one-way datagrams:
+ * a lost frame is acceptable because the transcript resynchronizes from the next
+ * snapshot, and retransmitting ordered frames over an unreliable transport would
+ * need a much larger protocol than this lane is worth.
+ */
+
+export async function createP2pNode({ localPort, bindPort = 0, keyFor, selfDeviceId, log = console }) {
+  const streams = new Map() // streamId -> { onChunk, onEnd }
+  let nextStreamId = 1
+
+  function forward(inner) {
+    return new Promise((resolve) => {
+      const text = typeof inner?.bodyText === 'string' ? inner.bodyText : ''
+      const request = http.request({
+        host: '127.0.0.1',
+        port: localPort,
+        path: typeof inner?.path === 'string' ? inner.path : '/',
+        method: inner?.method || 'GET',
+        headers: {
+          ...(inner?.headers ?? {}),
+          host: `127.0.0.1:${localPort}`,
+          'x-dsh-via': 'p2p',
+          'content-length': Buffer.byteLength(text),
+        },
+        timeout: 10000,
+      }, (response) => {
+        let data = ''
+        response.on('data', (chunk) => { data += chunk })
+        response.on('end', () => resolve({ status: response.statusCode ?? 502, bodyText: data }))
+      })
+      request.on('timeout', () => request.destroy(new Error('timeout')))
+      request.on('error', () => resolve({ status: 502, bodyText: '' }))
+      request.end(text || undefined)
+    })
+  }
+
+  /** Forward one SSE stream to a peer as datagrams. */
+  function relayStream(remote, box, inner, streamId) {
+    const request = http.request({
+      host: '127.0.0.1',
+      port: localPort,
+      path: typeof inner?.path === 'string' ? inner.path : '/',
+      method: 'GET',
+      headers: {
+        ...(inner?.headers ?? {}),
+        host: `127.0.0.1:${localPort}`,
+        'x-dsh-via': 'p2p',
+        accept: 'text/event-stream',
+      },
+      timeout: 15000,
+    }, (response) => {
+      response.setEncoding('utf8')
+      response.on('data', (chunk) => {
+        channel.notify(remote, { from: selfDeviceId, box: box.seal(JSON.stringify({ streamChunk: streamId, chunk })) })
+      })
+      response.on('end', () => {
+        channel.notify(remote, { from: selfDeviceId, box: box.seal(JSON.stringify({ streamEnd: streamId })) })
+      })
+    })
+    request.on('timeout', () => request.destroy(new Error('timeout')))
+    request.on('error', () => { /* the peer sees the stream stall and retries */ })
+    request.end()
+  }
+
+  async function handleDatagram(message, rinfo) {
+    // The punch probe is authenticated too: an open responder would answer any
+    // datagram and hand out a reflection surface.
+    if (typeof message?.box !== 'string') return { error: 'bad-envelope' }
+    const deviceId = String(message.from || '')
+    const box = keyFor(deviceId)
+    if (!box || typeof box.open !== 'function') return { error: 'no-channel' }
+    let inner
+    try {
+      inner = JSON.parse(box.open(message.box).toString('utf8'))
+    } catch {
+      return { error: 'bad-envelope' }
+    }
+
+    if (inner?.punch === true) return { box: box.seal(JSON.stringify({ pong: true })) }
+
+    if (inner?.streamOpen) {
+      relayStream(rinfo, box, inner.streamOpen, inner.streamId)
+      return { ok: true }
+    }
+    if (typeof inner?.streamChunk === 'number') {
+      streams.get(inner.streamChunk)?.onChunk?.(String(inner.chunk ?? ''))
+      return { ok: true }
+    }
+    if (typeof inner?.streamEnd === 'number') {
+      const entry = streams.get(inner.streamEnd)
+      streams.delete(inner.streamEnd)
+      entry?.onEnd?.()
+      return { ok: true }
+    }
+
+    const result = await forward(inner)
+    return { box: box.seal(JSON.stringify(result)) }
+  }
+
+  const channel = await createUdpChannel({ bindPort, handler: handleDatagram })
+
+  async function request(remote, deviceId, inner) {
+    const box = keyFor(deviceId)
+    if (!box) return { ok: false, error: 'no-channel' }
+    const result = await channel.request(remote, { from: selfDeviceId, box: box.seal(JSON.stringify(inner)) })
+    if (!result.ok) return result
+    const reply = result.message
+    if (typeof reply?.box !== 'string') return { ok: false, error: reply?.error || 'bad-reply' }
+    try {
+      return { ok: true, message: JSON.parse(box.open(reply.box).toString('utf8')) }
+    } catch {
+      return { ok: false, error: 'bad-reply' }
+    }
+  }
+
+  function openStream(remote, deviceId, inner, handlers = {}) {
+    const box = keyFor(deviceId)
+    if (!box) return { ok: false, error: 'no-channel' }
+    const streamId = nextStreamId++
+    streams.set(streamId, handlers)
+    channel.notify(remote, {
+      from: selfDeviceId,
+      box: box.seal(JSON.stringify({ streamOpen: inner, streamId })),
+    })
+    return {
+      ok: true,
+      streamId,
+      close: () => {
+        streams.delete(streamId)
+        const current = keyFor(deviceId)
+        if (current) {
+          channel.notify(remote, { from: selfDeviceId, box: current.seal(JSON.stringify({ streamEnd: streamId })) })
+        }
+      },
+    }
+  }
+
+  return {
+    port: channel.port,
+    request,
+    openStream,
+    mapped: (options) => channel.stun(options),
+    async punch(remote, deviceId) {
+      const box = keyFor(deviceId)
+      if (!box) return { ok: false, error: 'no-channel' }
+      const result = await channel.request(remote, { from: selfDeviceId, box: box.seal(JSON.stringify({ punch: true })) })
+      if (!result.ok) return { ok: false, error: result.error || 'no-pong' }
+      if (typeof result.message?.box !== 'string') return { ok: false, error: result.message?.error || 'no-pong' }
+      try {
+        const reply = JSON.parse(box.open(result.message.box).toString('utf8'))
+        return reply?.pong === true ? { ok: true } : { ok: false, error: 'no-pong' }
+      } catch {
+        return { ok: false, error: 'bad-reply' }
+      }
+    },
+    close: () => channel.close(),
+  }
+}
+
+export { createBoxCipher }

package/host/punch.js

@@ -0,0 +1,69 @@
+import dgram from 'node:dgram'
+import { randomBytes } from 'node:crypto'
+
+/**
+ * UDP hole-punch exchange (Phase B).
+ *
+ * Both sides send a small HELLO packet to each of the peer's advertised
+ * candidates on an interval; the first packet to arrive proves the NAT mapping
+ * and the socket becomes the direct lane. Retries continue until the timeout
+ * because the two sides' first sends rarely cross.
+ *
+ * This is the exchange only. On a network without NAT the same code path runs
+ * between two bound sockets, which is exactly how scripts/punch-test.mjs
+ * verifies it; on two real NATs it still needs a live trial.
+ */
+
+const MAGIC = Buffer.from('DSHPUNCH1', 'utf8')
+
+export async function createPuncher({ intervalMs = 200, bindPort = 0 } = {}) {
+  const socket = dgram.createSocket('udp4')
+  let settled
+  let timer
+  let resolveDone
+  const done = new Promise((resolve) => { resolveDone = resolve })
+
+  function finish(value) {
+    if (settled) return
+    settled = value
+    clearInterval(timer)
+    try { socket.close() } catch { /* already closed */ }
+    resolveDone(value)
+  }
+
+  socket.on('message', (message, rinfo) => {
+    if (message.length >= MAGIC.length && message.subarray(0, MAGIC.length).equals(MAGIC)) {
+      finish({ ok: true, address: rinfo.address, port: rinfo.port })
+    }
+  })
+  socket.on('error', (error) => finish({ ok: false, error: error?.message || 'socket-error' }))
+
+  await new Promise((resolve, reject) => {
+    socket.once('error', reject)
+    socket.bind(bindPort, resolve)
+  })
+  const port = socket.address().port
+
+  function start(candidates, timeoutMs = 3000) {
+    if (settled) return Promise.resolve(settled)
+    const targets = (candidates ?? []).filter((entry) => entry && entry.address && entry.port)
+    const packet = Buffer.concat([MAGIC, randomBytes(4)])
+    const send = () => {
+      for (const target of targets) {
+        try { socket.send(packet, 0, packet.length, target.port, target.address) } catch { /* candidate unreachable */ }
+      }
+    }
+    send()
+    timer = setInterval(send, intervalMs)
+    timer.unref?.()
+    const deadline = setTimeout(() => finish({ ok: false, error: 'timeout' }), timeoutMs)
+    deadline.unref?.()
+    return done
+  }
+
+  return {
+    port: () => port,
+    start,
+    close: () => finish({ ok: false, error: 'closed' }),
+  }
+}