dsh-device-fleet 0.0.0-stage → 0.1.0-dev.1

package/src/net/fleet-node.js

@@ -0,0 +1,414 @@
+// FleetNode: one device's networking facade.
+//
+// It owns the identity, the fleet roster, a direct listener, optional LAN
+// discovery, an optional relay client, and the RPC layer that runs over
+// authenticated SecureChannels.
+import { EventEmitter } from 'node:events'
+import { randomUUID } from 'node:crypto'
+import { createDirectServer, connectDirect } from './direct.js'
+import { LanDiscovery } from './discovery.js'
+import { RelayClient } from './relay-client.js'
+import { SecureChannel } from './secure-channel.js'
+import {
+  FRAME,
+  PROTOCOL_VERSION,
+  eventFrame,
+  rpcError,
+  rpcRequest,
+  rpcResult,
+  serializeError,
+} from './protocol.js'
+
+const DEFAULT_CONNECT_TIMEOUT_MS = 12_000
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000
+
+export class FleetNode extends EventEmitter {
+  /**
+   * @param {object} options
+   * @param {object} options.identity device identity (generateIdentity)
+   * @param {{fleetId: string, fleetKey: string, name?: string}} options.fleet
+   * @param {string} [options.name]
+   * @param {string|null} [options.accountFingerprint]
+   * @param {{host?: string, port?: number}|false} [options.direct] direct listener (false disables)
+   * @param {false|{group?: string, port?: number, intervalMs?: number}} [options.discovery]
+   * @param {null|{host: string, port: number, dataPort: number, reconnect?: object}} [options.relay]
+   * @param {Array<{deviceId: string, edPublic: string, xPublic: string, name?: string}>} [options.roster]
+   * @param {boolean} [options.trustOnFirstUse]
+   * @param {boolean} [options.acceptRelayConnections]
+   */
+  constructor({
+    identity,
+    fleet,
+    name = identity?.name ?? 'device',
+    accountFingerprint = null,
+    direct = { host: '127.0.0.1', port: 0 },
+    discovery = false,
+    relay = null,
+    roster = [],
+    trustOnFirstUse = true,
+    acceptRelayConnections = true,
+    connectTimeoutMs = DEFAULT_CONNECT_TIMEOUT_MS,
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
+    pluginVersion = '0.1.0',
+    dshVersion = 'unknown',
+    capabilities = [],
+  } = {}) {
+    super()
+    if (!identity?.deviceId || !identity.edPrivate || !identity.edPublic) throw new Error('FleetNode needs an identity')
+    if (!fleet?.fleetId || !fleet?.fleetKey) throw new Error('FleetNode needs a fleet')
+    this.identity = identity
+    this.fleet = fleet
+    this.name = name
+    this.accountFingerprint = accountFingerprint
+    this.directConfig = direct
+    this.discoveryConfig = discovery
+    this.relayConfig = relay
+    this.trustOnFirstUse = trustOnFirstUse
+    this.acceptRelayConnections = acceptRelayConnections
+    this.connectTimeoutMs = connectTimeoutMs
+    this.requestTimeoutMs = requestTimeoutMs
+    this.pluginVersion = pluginVersion
+    this.dshVersion = dshVersion
+    this.capabilities = capabilities
+
+    this.roster = new Map()
+    for (const entry of roster) this.roster.set(entry.deviceId, { name: 'device', ...entry })
+    this.discovered = new Map()
+    this.channels = new Map()
+    this.pendingRpc = new Map()
+    this.requestHandler = null
+    this.eventHandler = null
+
+    this.directServer = null
+    this.discovery = null
+    this.relayClient = null
+    this.started = false
+    this.closed = false
+  }
+
+  get directPort() {
+    return this.directAddress?.port ?? null
+  }
+
+  rosterEntries() {
+    return [...this.roster.values()]
+  }
+
+  upsertRoster(entry) {
+    const existing = this.roster.get(entry.deviceId)
+    this.roster.set(entry.deviceId, { ...existing, name: 'device', ...entry })
+    this.emit('roster', this.rosterEntries())
+  }
+
+  onRequest(handler) {
+    this.requestHandler = handler
+  }
+
+  onEvent(handler) {
+    this.eventHandler = handler
+  }
+
+  async start() {
+    if (this.started) return this
+    this.started = true
+
+    if (this.directConfig !== false) {
+      this.directServer = createDirectServer({
+        host: this.directConfig.host ?? '0.0.0.0',
+        port: this.directConfig.port ?? 0,
+      })
+      this.directAddress = await this.directServer.ready
+      this.directServer.server.on('connection', (socket) => this.acceptInbound(socket, 'direct'))
+    }
+
+    if (this.discoveryConfig !== false && this.discoveryConfig !== undefined) {
+      if (!this.directAddress) throw new Error('discovery needs the direct listener')
+      const config = this.discoveryConfig === true ? {} : this.discoveryConfig
+      this.discovery = new LanDiscovery({
+        fleetId: this.fleet.fleetId,
+        deviceId: this.identity.deviceId,
+        name: this.name,
+        directPort: this.directAddress.port,
+        group: config.group,
+        port: config.port,
+        intervalMs: config.intervalMs,
+      })
+      this.discovery.on('peer', (peer) => {
+        this.discovered.set(peer.deviceId, peer)
+        this.emit('discovered', peer)
+      })
+      this.discovery.on('error', (error) => this.emit('warning', error))
+      this.discovery.start()
+    }
+
+    if (this.relayConfig) {
+      this.relayClient = new RelayClient({
+        host: this.relayConfig.host,
+        port: this.relayConfig.port,
+        dataPort: this.relayConfig.dataPort,
+        fleetId: this.fleet.fleetId,
+        deviceId: this.identity.deviceId,
+        fleetKey: this.fleet.fleetKey,
+        reconnect: this.relayConfig.reconnect,
+      })
+      this.relayClient.on('online', () => this.emit('relay-online'))
+      this.relayClient.on('offline', () => this.emit('relay-offline'))
+      this.relayClient.on('relay-error', (error) => this.emit('warning', error))
+      this.relayClient.on('incoming', (controller) => this.acceptIncomingRelay(controller))
+      try {
+        await this.relayClient.start(5_000)
+      } catch (error) {
+        this.emit('warning', error)
+      }
+    }
+
+    this.emit('started', { direct: this.directAddress ?? null })
+    return this
+  }
+
+  async acceptIncomingRelay(controller) {
+    if (!this.acceptRelayConnections) {
+      controller.reject()
+      return
+    }
+    try {
+      const socket = await controller.accept()
+      this.acceptInbound(socket, 'relay')
+    } catch (error) {
+      this.emit('warning', error)
+    }
+  }
+
+  acceptInbound(socket, via) {
+    const channel = new SecureChannel({
+      socket,
+      identity: this.identity,
+      fleet: this.fleet,
+      role: 'responder',
+      accountFingerprint: this.accountFingerprint,
+      verifyPeer: (peer) => this.authorizePeer(peer),
+      pluginVersion: this.pluginVersion,
+      dshVersion: this.dshVersion,
+      capabilities: this.capabilities,
+    })
+    this.attachChannel(channel, via)
+  }
+
+  attachChannel(channel, via) {
+    channel.on('error', (error) => this.emit('warning', error))
+    channel.on('ready', (peer) => {
+      this.registerChannel(peer, channel, via)
+    })
+    channel.on('close', () => {
+      const current = this.channels.get(channel.peer?.deviceId)
+      if (current === channel) this.channels.delete(channel.peer.deviceId)
+      this.rejectPendingForChannel(channel, Object.assign(new Error('peer connection closed'), { code: 'peer-offline' }))
+      this.emit('peer-disconnected', { deviceId: channel.peer?.deviceId, via })
+    })
+  }
+
+  registerChannel(peer, channel, via) {
+    this.channels.set(peer.deviceId, channel)
+    channel.on('frame', (message) => this.onFrame(peer.deviceId, message, channel))
+    this.emit('peer', { deviceId: peer.deviceId, name: peer.name, via, channel })
+  }
+
+  authorizePeer(peer) {
+    const existing = this.roster.get(peer.deviceId)
+    if (existing) {
+      return existing.edPublic === peer.edPublic && existing.xPublic === peer.xPublic
+    }
+    if (!this.trustOnFirstUse) return false
+    this.roster.set(peer.deviceId, {
+      deviceId: peer.deviceId,
+      name: peer.name ?? 'device',
+      edPublic: peer.edPublic,
+      xPublic: peer.xPublic,
+      addedAt: Date.now(),
+    })
+    this.emit('roster', this.rosterEntries())
+    return true
+  }
+
+  async connect(deviceId, { host, port, timeoutMs = this.connectTimeoutMs } = {}) {
+    if (typeof deviceId !== 'string' || deviceId === '') throw new Error('connect needs a device id')
+    if (deviceId === this.identity.deviceId) throw new Error('cannot connect to self')
+    const existing = this.channels.get(deviceId)
+    if (existing && !existing.closed) return existing
+
+    const expected = this.roster.get(deviceId) ?? { deviceId }
+    const discovered = this.discovered.get(deviceId)
+    const endpoint = host && port ? { host, port } : discovered ? { host: discovered.host, port: discovered.port } : null
+    let directError = null
+    if (endpoint) {
+      try {
+        const socket = await connectDirect({ host: endpoint.host, port: endpoint.port, timeoutMs })
+        const channel = this.createInitiator(socket, expected)
+        await this.waitReady(channel, timeoutMs)
+        return channel
+      } catch (error) {
+        directError = error
+      }
+    }
+    if (this.relayClient) {
+      try {
+        const socket = await this.relayClient.requestConnect(deviceId, timeoutMs)
+        const channel = this.createInitiator(socket, expected)
+        await this.waitReady(channel, timeoutMs)
+        return channel
+      } catch (error) {
+        throw Object.assign(new Error(`cannot reach ${deviceId} via relay: ${String(error.message)}`), {
+          code: 'unreachable',
+          cause: error,
+        })
+      }
+    }
+    throw Object.assign(
+      new Error(`cannot reach ${deviceId}${directError ? `: ${String(directError.message)}` : ' (no endpoint)'}`),
+      { code: 'unreachable', cause: directError ?? undefined },
+    )
+  }
+
+  createInitiator(socket, expectedPeer) {
+    const channel = new SecureChannel({
+      socket,
+      identity: this.identity,
+      fleet: this.fleet,
+      role: 'initiator',
+      expectedPeer,
+      accountFingerprint: this.accountFingerprint,
+      verifyPeer: (peer) => this.authorizePeer(peer),
+      pluginVersion: this.pluginVersion,
+      dshVersion: this.dshVersion,
+      capabilities: this.capabilities,
+    })
+    this.attachChannel(channel, 'outbound')
+    return channel
+  }
+
+  waitReady(channel, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      if (channel.authenticated) return resolve(channel)
+      const timer = setTimeout(() => {
+        cleanup()
+        reject(Object.assign(new Error('secure channel handshake timed out'), { code: 'handshake-timeout' }))
+        channel.destroy()
+      }, timeoutMs)
+      timer.unref?.()
+      const onReady = () => {
+        cleanup()
+        resolve(channel)
+      }
+      const onClose = () => {
+        cleanup()
+        reject(Object.assign(new Error('secure channel closed during handshake'), { code: 'handshake-closed' }))
+      }
+      const cleanup = () => {
+        clearTimeout(timer)
+        channel.off('ready', onReady)
+        channel.off('close', onClose)
+      }
+      channel.once('ready', onReady)
+      channel.once('close', onClose)
+    })
+  }
+
+  onFrame(deviceId, message, channel) {
+    switch (message.t) {
+      case FRAME.RPC_REQUEST: {
+        const handler = this.requestHandler
+        if (typeof handler !== 'function') {
+          channel.sendFrame(rpcError({ id: message.id, code: 'no-handler', message: 'no request handler' }))
+          return
+        }
+        Promise.resolve()
+          .then(() => handler({ deviceId, method: message.method, params: message.params }))
+          .then((result) => channel.sendFrame(rpcResult({ id: message.id, result })))
+          .catch((error) => {
+            channel.sendFrame(rpcError({ id: message.id, ...serializeError(error) }))
+          })
+        return
+      }
+      case FRAME.RPC_RESULT: {
+        const pending = this.pendingRpc.get(message.id)
+        if (!pending) return
+        this.pendingRpc.delete(message.id)
+        clearTimeout(pending.timer)
+        pending.resolve(message.result)
+        return
+      }
+      case FRAME.RPC_ERROR: {
+        const pending = this.pendingRpc.get(message.id)
+        if (!pending) return
+        this.pendingRpc.delete(message.id)
+        clearTimeout(pending.timer)
+        const error = new Error(message.error?.message ?? 'remote error')
+        error.code = message.error?.code ?? 'remote-error'
+        error.data = message.error?.data ?? null
+        pending.reject(error)
+        return
+      }
+      case FRAME.EVENT: {
+        this.emit('event', { deviceId, topic: message.topic, data: message.data })
+        return
+      }
+      default:
+        return
+    }
+  }
+
+  rejectPendingForChannel(channel, error) {
+    for (const [id, pending] of this.pendingRpc) {
+      if (pending.channel === channel) {
+        this.pendingRpc.delete(id)
+        clearTimeout(pending.timer)
+        pending.reject(error)
+      }
+    }
+  }
+
+  async request(deviceId, method, params, { timeoutMs = this.requestTimeoutMs } = {}) {
+    const channel = await this.connect(deviceId)
+    const id = randomUUID()
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRpc.delete(id)
+        reject(Object.assign(new Error(`request ${method} to ${deviceId} timed out`), { code: 'timeout' }))
+      }, timeoutMs)
+      timer.unref?.()
+      this.pendingRpc.set(id, { resolve, reject, timer, channel })
+      try {
+        channel.sendFrame(rpcRequest({ id, method, params }))
+      } catch (error) {
+        this.pendingRpc.delete(id)
+        clearTimeout(timer)
+        reject(error)
+      }
+    })
+  }
+
+  async sendEvent(deviceId, topic, data) {
+    const channel = await this.connect(deviceId)
+    channel.sendFrame(eventFrame({ topic, data }))
+  }
+
+  peerIds() {
+    return [...this.channels.keys()]
+  }
+
+  async close() {
+    this.closed = true
+    for (const channel of this.channels.values()) channel.close()
+    this.channels.clear()
+    for (const [id, pending] of this.pendingRpc) {
+      this.pendingRpc.delete(id)
+      clearTimeout(pending.timer)
+      pending.reject(Object.assign(new Error('node closed'), { code: 'closed' }))
+    }
+    this.relayClient?.close()
+    this.discovery?.close()
+    if (this.directServer) await this.directServer.close()
+  }
+}
+
+export { PROTOCOL_VERSION }

package/src/net/identity.js

@@ -0,0 +1,156 @@
+// Device identity, fleet invites and membership proofs.
+//
+// Every device owns an Ed25519 keypair (authentication) and an X25519 keypair
+// (key agreement). A Fleet is identified by `fleetId` and a shared 32-byte
+// `fleetKey` carried by invites; the key proves membership and bootstraps trust
+// on first contact (TOFU), after which peer public keys are pinned in the roster.
+import {
+  createHash,
+  createHmac,
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  randomBytes,
+  randomUUID,
+} from 'node:crypto'
+
+const INVITE_PREFIX = 'DSHF1.'
+const PROOF_PREFIX = 'member'
+const RELAY_PREFIX = 'relay-register'
+const ACCOUNT_PREFIX = 'account'
+
+export function exportKey(key) {
+  return key.export({ type: key.type === 'private' ? 'pkcs8' : 'spki', format: 'pem' }).toString()
+}
+
+export function importPrivateKey(pem) {
+  return createPrivateKey(pem)
+}
+
+export function importPublicKey(pem) {
+  return createPublicKey(pem)
+}
+
+function randomBase64Url(bytes) {
+  return randomBytes(bytes).toString('base64url')
+}
+
+/** A fresh device identity. Caller persists it (e.g. `$DSH_HOME/device-fleet/identity.json`). */
+export function generateIdentity({ name = 'device' } = {}) {
+  const ed = generateKeyPairSync('ed25519')
+  const x = generateKeyPairSync('x25519')
+  return {
+    deviceId: randomUUID(),
+    name,
+    createdAt: Date.now(),
+    edPrivate: exportKey(ed.privateKey),
+    edPublic: exportKey(ed.publicKey),
+    xPrivate: exportKey(x.privateKey),
+    xPublic: exportKey(x.publicKey),
+  }
+}
+
+/** Public half of an identity, safe to put in a roster/invite. */
+export function publicIdentity(identity) {
+  return {
+    deviceId: identity.deviceId,
+    name: identity.name,
+    edPublic: identity.edPublic,
+    xPublic: identity.xPublic,
+  }
+}
+
+/** A new fleet. `fleetKey` is the fleet-wide membership secret carried by invites. */
+export function createFleet({ name = 'fleet' } = {}) {
+  return {
+    fleetId: randomUUID(),
+    fleetKey: randomBase64Url(32),
+    name,
+    createdAt: Date.now(),
+  }
+}
+
+export function encodeInvite({ fleet, accountFingerprint = null, relay = null }) {
+  const payload = {
+    v: 1,
+    fleetId: fleet.fleetId,
+    fleetKey: fleet.fleetKey,
+    name: fleet.name,
+    accountFingerprint,
+    relay,
+    createdAt: Date.now(),
+  }
+  return INVITE_PREFIX + Buffer.from(JSON.stringify(payload)).toString('base64url')
+}
+
+export function decodeInvite(code) {
+  if (typeof code !== 'string' || !code.startsWith(INVITE_PREFIX)) throw new Error('invalid invite')
+  const raw = code.slice(INVITE_PREFIX.length)
+  let payload
+  try {
+    payload = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'))
+  } catch {
+    throw new Error('invalid invite payload')
+  }
+  if (payload?.v !== 1 || typeof payload.fleetId !== 'string' || typeof payload.fleetKey !== 'string') {
+    throw new Error('unsupported invite')
+  }
+  return {
+    fleet: { fleetId: payload.fleetId, fleetKey: payload.fleetKey, name: payload.name ?? 'fleet' },
+    accountFingerprint: payload.accountFingerprint ?? null,
+    relay: payload.relay ?? null,
+    createdAt: payload.createdAt ?? null,
+  }
+}
+
+/** Account fingerprint: proves "same account" inside the fleet without exposing the account id. */
+export function accountFingerprint(fleetKey, accountUserId) {
+  if (!accountUserId) return null
+  return createHmac('sha256', fleetKey).update(`${ACCOUNT_PREFIX}|${accountUserId}`).digest('base64url')
+}
+
+/** HMAC proof that this device belongs to the fleet (checked by peers during the handshake). */
+export function membershipProof({ fleetKey, fleetId, deviceId, edPublic, xPublic, accountFingerprint = null }) {
+  return createHmac('sha256', fleetKey)
+    .update(`${PROOF_PREFIX}|${fleetId}|${deviceId}|${edPublic}|${xPublic}|${accountFingerprint ?? ''}`)
+    .digest('base64url')
+}
+
+export function verifyMembershipProof(proof, fields) {
+  const expected = membershipProof(fields)
+  const a = Buffer.from(String(proof))
+  const b = Buffer.from(expected)
+  return a.length === b.length && a.equals(b)
+}
+
+/** `fleetId` hash advertised in LAN announcements (the full id stays off the wire). */
+export function fleetHash(fleetId) {
+  return createHash('sha256').update(`fleet|${fleetId}`).digest('hex').slice(0, 16)
+}
+
+export function shortFingerprint(edPublic, xPublic) {
+  return createHash('sha256')
+    .update(`${edPublic}|${xPublic}`)
+    .digest('hex')
+    .slice(0, 16)
+}
+
+/** Token proving fleet membership to a self-hosted relay. */
+export function relayAuthToken({ fleetKey, fleetId, deviceId, ts }) {
+  return createHmac('sha256', fleetKey)
+    .update(`${RELAY_PREFIX}|${fleetId}|${deviceId}|${ts}`)
+    .digest('base64url')
+}
+
+export function verifyRelayAuthToken(token, { fleetKey, fleetId, deviceId, ts }) {
+  const expected = relayAuthToken({ fleetKey, fleetId, deviceId, ts })
+  const a = Buffer.from(String(token))
+  const b = Buffer.from(expected)
+  return a.length === b.length && a.equals(b)
+}
+
+/** Ephemeral X25519 pair for one handshake. */
+export function generateEphemeral() {
+  const pair = generateKeyPairSync('x25519')
+  return { privateKey: pair.privateKey, publicKey: exportKey(pair.publicKey), privateKeyPem: exportKey(pair.privateKey) }
+}

package/src/net/index.js

@@ -0,0 +1,9 @@
+// Network layer exports.
+export * from './identity.js'
+export * from './protocol.js'
+export * from './secure-channel.js'
+export * from './direct.js'
+export * from './discovery.js'
+export * from './relay-server.js'
+export * from './relay-client.js'
+export * from './fleet-node.js'

package/src/net/protocol.js

@@ -0,0 +1,73 @@
+// Wire protocol constants, canonical JSON and RPC envelope helpers.
+
+export const PROTOCOL_VERSION = 1
+
+/** Largest accepted frame payload (ciphertext bytes, excluding the length prefix). */
+export const MAX_FRAME_BYTES = 32 * 1024 * 1024
+
+/** Handshake messages are newline-delimited JSON; encrypted frames are length-prefixed. */
+export const HANDSHAKE_TIMEOUT_MS = 10_000
+
+export const FRAME = Object.freeze({
+  READY: 'ready',
+  RPC_REQUEST: 'rpc.req',
+  RPC_RESULT: 'rpc.res',
+  RPC_ERROR: 'rpc.err',
+  EVENT: 'event',
+  PING: 'ping',
+  PONG: 'pong',
+})
+
+export function stableStringify(value) {
+  return JSON.stringify(sortValue(value))
+}
+
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map(sortValue)
+  if (value && typeof value === 'object') {
+    const out = {}
+    for (const key of Object.keys(value).sort()) out[key] = sortValue(value[key])
+    return out
+  }
+  return value
+}
+
+export function rpcRequest({ id, method, params }) {
+  return { t: FRAME.RPC_REQUEST, v: PROTOCOL_VERSION, id, method, params: params ?? null }
+}
+
+export function rpcResult({ id, result }) {
+  return { t: FRAME.RPC_RESULT, v: PROTOCOL_VERSION, id, result: result ?? null }
+}
+
+export function rpcError({ id, code, message, data = null }) {
+  return { t: FRAME.RPC_ERROR, v: PROTOCOL_VERSION, id, error: { code, message, data } }
+}
+
+export function eventFrame({ topic, data }) {
+  return { t: FRAME.EVENT, v: PROTOCOL_VERSION, topic, data: data ?? null }
+}
+
+export function pingFrame() {
+  return { t: FRAME.PING, v: PROTOCOL_VERSION }
+}
+
+export function pongFrame() {
+  return { t: FRAME.PONG, v: PROTOCOL_VERSION }
+}
+
+export function serializeError(error) {
+  if (!error) return { code: 'internal', message: 'unknown error', data: null }
+  return {
+    code: typeof error.code === 'string' ? error.code : 'internal',
+    message: String(error.message ?? error),
+    data: error.data ?? null,
+  }
+}
+
+export function makeError(code, message, data = null) {
+  const error = new Error(message)
+  error.code = code
+  error.data = data
+  return error
+}