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

package/src/net/identity.js

@@ -0,0 +1,167 @@
+// 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, endpoints = [] }) {
+  const payload = {
+    v: 1,
+    fleetId: fleet.fleetId,
+    fleetKey: fleet.fleetKey,
+    name: fleet.name,
+    accountFingerprint,
+    relay,
+    endpoints: Array.isArray(endpoints) ? endpoints : [],
+    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,
+    endpoints: Array.isArray(payload.endpoints)
+      ? payload.endpoints.filter(
+          (entry) =>
+            entry &&
+            typeof entry.host === 'string' &&
+            Number.isInteger(entry.port) &&
+            entry.port > 0 &&
+            (entry.deviceId === undefined || typeof entry.deviceId === 'string'),
+        )
+      : [],
+    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
+}

package/src/net/relay-client.js

@@ -0,0 +1,258 @@
+// Relay client: keeps a control connection to the self-hosted relay and opens
+// spliced data connections to other fleet devices.
+import { EventEmitter } from 'node:events'
+import net from 'node:net'
+import { randomUUID } from 'node:crypto'
+import { relayAuthToken } from './identity.js'
+
+const DEFAULT_CONNECT_TIMEOUT_MS = 15_000
+
+export class RelayClient extends EventEmitter {
+  /**
+   * @param {object} options
+   * @param {string} options.host relay host
+   * @param {number} options.port relay control port
+   * @param {number} options.dataPort relay data port
+   * @param {string} options.fleetId
+   * @param {string} options.deviceId
+   * @param {string} options.fleetKey
+   * @param {{initialDelayMs?: number, maxDelayMs?: number}} [options.reconnect]
+   */
+  constructor({ host, port, dataPort, fleetId, deviceId, fleetKey, reconnect = {} }) {
+    super()
+    this.host = host
+    this.port = port
+    this.dataPort = dataPort
+    this.fleetId = fleetId
+    this.deviceId = deviceId
+    this.fleetKey = fleetKey
+    this.reconnect = { initialDelayMs: 500, maxDelayMs: 10_000, ...reconnect }
+
+    this.socket = null
+    this.buffer = ''
+    this.online = false
+    this.closed = false
+    this.attempt = 0
+    this.reconnectTimer = null
+    this.waiters = new Set()
+    this.readyWaiters = new Map()
+    this.controllers = new Map()
+  }
+
+  /** Start connecting; resolves once registered (or rejects on timeout). */
+  async start(timeoutMs = 5_000) {
+    if (this.socket) return
+    this.connect()
+    await this.whenOnline(timeoutMs)
+  }
+
+  whenOnline(timeoutMs = 5_000) {
+    if (this.online) return Promise.resolve()
+    return new Promise((resolve, reject) => {
+      const waiter = { resolve, reject }
+      this.waiters.add(waiter)
+      const timer = setTimeout(() => {
+        this.waiters.delete(waiter)
+        reject(new Error('relay connection timed out'))
+      }, timeoutMs)
+      timer.unref?.()
+      waiter.timer = timer
+    })
+  }
+
+  connect() {
+    if (this.closed) return
+    const socket = net.connect({ host: this.host, port: this.port })
+    this.socket = socket
+    this.buffer = ''
+    socket.setNoDelay?.(true)
+    socket.once('connect', () => {
+      const ts = Date.now()
+      this.send({
+        t: 'register',
+        fleetId: this.fleetId,
+        deviceId: this.deviceId,
+        ts,
+        token: relayAuthToken({ fleetKey: this.fleetKey, fleetId: this.fleetId, deviceId: this.deviceId, ts }),
+      })
+    })
+    socket.on('data', (chunk) => this.onData(chunk))
+    socket.on('error', () => {})
+    socket.once('close', () => this.onClose(socket))
+  }
+
+  send(message) {
+    if (!this.socket || this.socket.destroyed || !this.socket.writable) return false
+    this.socket.write(JSON.stringify(message) + '\n')
+    return true
+  }
+
+  onData(chunk) {
+    this.buffer += chunk.toString('utf8')
+    let newline = this.buffer.indexOf('\n')
+    while (newline >= 0) {
+      const line = this.buffer.slice(0, newline)
+      this.buffer = this.buffer.slice(newline + 1)
+      if (line.trim() !== '') this.onMessage(line)
+      newline = this.buffer.indexOf('\n')
+    }
+  }
+
+  onMessage(line) {
+    let message
+    try {
+      message = JSON.parse(line)
+    } catch {
+      return
+    }
+    switch (message?.t) {
+      case 'register.ok': {
+        this.online = true
+        this.attempt = 0
+        for (const waiter of this.waiters) {
+          this.waiters.delete(waiter)
+          clearTimeout(waiter.timer)
+          waiter.resolve()
+        }
+        this.emit('online', { deviceId: this.deviceId })
+        return
+      }
+      case 'error': {
+        this.emit('relay-error', message)
+        if (message.code === 'unauthorized' || message.code === 'unknown-fleet' || message.code === 'replaced') {
+          this.closed = true
+          this.socket?.destroy()
+        }
+        return
+      }
+      case 'incoming': {
+        const { reqId, fromDeviceId } = message
+        const controller = {
+          reqId,
+          fromDeviceId,
+          decided: false,
+          accept: () => this.acceptIncoming(controller),
+          reject: () => {
+            controller.decided = true
+            this.controllers.delete(reqId)
+            this.send({ t: 'reject', reqId })
+          },
+        }
+        this.controllers.set(reqId, controller)
+        this.emit('incoming', controller)
+        return
+      }
+      case 'connect.pending':
+        return
+      case 'connect.ready': {
+        const waiter = this.readyWaiters.get(message.reqId)
+        if (!waiter) return
+        this.readyWaiters.delete(message.reqId)
+        clearTimeout(waiter.timer)
+        waiter.resolve({ dataPort: message.dataPort, token: message.token })
+        return
+      }
+      case 'connect.fail': {
+        const waiter = this.readyWaiters.get(message.reqId)
+        if (waiter) {
+          this.readyWaiters.delete(message.reqId)
+          clearTimeout(waiter.timer)
+          waiter.reject(Object.assign(new Error(`relay connect failed: ${message.reason}`), { code: message.reason }))
+        }
+        const connectWaiter = this.connectWaiters?.get(message.reqId)
+        if (connectWaiter) {
+          this.connectWaiters.delete(message.reqId)
+          clearTimeout(connectWaiter.timer)
+          connectWaiter.reject(Object.assign(new Error(`relay connect failed: ${message.reason}`), { code: message.reason }))
+        }
+        return
+      }
+      default:
+        return
+    }
+  }
+
+  waitReady(reqId, timeoutMs = 15_000) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.readyWaiters.delete(reqId)
+        reject(Object.assign(new Error('relay data path timed out'), { code: 'data-timeout' }))
+      }, timeoutMs)
+      timer.unref?.()
+      this.readyWaiters.set(reqId, { resolve, reject, timer })
+    })
+  }
+
+  async acceptIncoming(controller) {
+    if (controller.decided) throw new Error('incoming request already settled')
+    controller.decided = true
+    this.controllers.delete(controller.reqId)
+    const ready = this.waitReady(controller.reqId)
+    this.send({ t: 'accept', reqId: controller.reqId })
+    const { dataPort, token } = await ready
+    return this.openDataSocket(controller.reqId, token, dataPort)
+  }
+
+  async requestConnect(targetDeviceId, timeoutMs = DEFAULT_CONNECT_TIMEOUT_MS) {
+    if (!this.online) await this.whenOnline(Math.min(timeoutMs, 5_000))
+    const reqId = randomUUID()
+    const ready = this.waitReady(reqId, timeoutMs)
+    this.send({ t: 'connect', reqId, targetDeviceId })
+    const { dataPort, token } = await ready
+    return this.openDataSocket(reqId, token, dataPort)
+  }
+
+  openDataSocket(reqId, token, dataPort = this.dataPort) {
+    return new Promise((resolve, reject) => {
+      const socket = net.connect({ host: this.host, port: dataPort })
+      const timer = setTimeout(() => {
+        socket.destroy()
+        reject(Object.assign(new Error('relay data connection timed out'), { code: 'data-timeout' }))
+      }, DEFAULT_CONNECT_TIMEOUT_MS)
+      timer.unref?.()
+      socket.setNoDelay?.(true)
+      socket.once('connect', () => {
+        clearTimeout(timer)
+        socket.write(
+          JSON.stringify({ fleetId: this.fleetId, deviceId: this.deviceId, reqId, token }) + '\n',
+        )
+        resolve(socket)
+      })
+      socket.once('error', (error) => {
+        clearTimeout(timer)
+        reject(error)
+      })
+    })
+  }
+
+  onClose(socket) {
+    if (this.socket !== socket) return
+    this.socket = null
+    const wasOnline = this.online
+    this.online = false
+    if (wasOnline) this.emit('offline')
+    for (const [reqId, waiter] of this.readyWaiters) {
+      this.readyWaiters.delete(reqId)
+      clearTimeout(waiter.timer)
+      waiter.reject(Object.assign(new Error('relay connection lost'), { code: 'relay-offline' }))
+    }
+    if (this.closed) return
+    const delay = Math.min(
+      this.reconnect.maxDelayMs,
+      this.reconnect.initialDelayMs * 2 ** Math.min(this.attempt++, 5),
+    )
+    this.reconnectTimer = setTimeout(() => this.connect(), delay)
+    this.reconnectTimer.unref?.()
+  }
+
+  close() {
+    this.closed = true
+    clearTimeout(this.reconnectTimer)
+    try {
+      this.socket?.destroy()
+    } catch {
+      /* ignore */
+    }
+    this.socket = null
+  }
+}