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

package/src/net/secure-channel.js

@@ -0,0 +1,538 @@
+// End-to-end secure channel between two fleet devices.
+//
+// Handshake (newline-delimited JSON):
+//   initiator -> responder : HELLO   (static keys + fleet proof + ephemeral X25519 + signature)
+//   responder -> initiator : HELLO_ACK
+//   both                   : encrypted READY frame
+// Then every frame is AES-256-GCM with per-direction keys derived from
+// X25519(ephemeral, ephemeral) + HKDF over the handshake transcript. The relay,
+// if used, only splices the underlying bytes and cannot read frames.
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  diffieHellman,
+  hkdfSync,
+  randomBytes,
+  sign,
+  verify,
+} from 'node:crypto'
+import { EventEmitter } from 'node:events'
+import {
+  FRAME,
+  HANDSHAKE_TIMEOUT_MS,
+  MAX_FRAME_BYTES,
+  PROTOCOL_VERSION,
+  stableStringify,
+} from './protocol.js'
+import {
+  generateEphemeral,
+  importPrivateKey,
+  importPublicKey,
+  membershipProof,
+  verifyMembershipProof,
+} from './identity.js'
+
+const AAD = Buffer.from('dsh-device-fleet/frame/v1')
+const MAX_CLOCK_SKEW_MS = 120_000
+
+function sha256(buffer) {
+  return createHash('sha256').update(buffer).digest()
+}
+
+function b64(buffer) {
+  return Buffer.from(buffer).toString('base64url')
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0
+}
+
+export class SecureChannel extends EventEmitter {
+  /**
+   * @param {object} options
+   * @param {import('node:net').Socket} options.socket connected socket
+   * @param {object} options.identity local identity ({deviceId, edPrivate, edPublic, xPublic, name})
+   * @param {{fleetId: string, fleetKey: string}} options.fleet
+   * @param {'initiator'|'responder'} options.role
+   * @param {object|null} [options.expectedPeer] pinned peer ({deviceId, edPublic, xPublic})
+   * @param {string|null} [options.accountFingerprint] expected account fingerprint
+   * @param {(peer: object) => boolean|Promise<boolean>} [options.verifyPeer] trust decision after protocol checks
+   * @param {string} [options.pluginVersion] strict plugin version (ADR-0024)
+   * @param {string} [options.dshVersion] strict harness version line (ADR-0024)
+   * @param {string[]} [options.capabilities] reserved capability declarations
+   */
+  constructor({
+    socket,
+    identity,
+    fleet,
+    role,
+    expectedPeer = null,
+    accountFingerprint = null,
+    verifyPeer = null,
+    pluginVersion = '0.0.0',
+    dshVersion = 'unknown',
+    capabilities = [],
+  }) {
+    super()
+    if (role !== 'initiator' && role !== 'responder') throw new Error('invalid channel role')
+    this.socket = socket
+    this.identity = identity
+    this.fleet = fleet
+    this.role = role
+    this.expectedPeer = expectedPeer
+    this.accountFingerprint = accountFingerprint
+    this.verifyPeer = verifyPeer
+    this.pluginVersion = pluginVersion
+    this.dshVersion = dshVersion
+    this.capabilities = [...capabilities].sort()
+
+    this.phase = 'handshake'
+    this.recvBuffer = Buffer.alloc(0)
+    this.readySent = false
+    this.readyReceived = false
+    this.authenticated = false
+    this.closed = false
+    this.peer = null
+    this.failure = null
+
+    this.sendKey = null
+    this.recvKey = null
+    this.sendPrefix = null
+    this.recvPrefix = null
+    this.sendCounter = 0n
+    this.recvCounter = 0n
+
+    this.handshakeTimer = setTimeout(() => {
+      this.fail('handshake-timeout', 'secure channel handshake timed out')
+    }, HANDSHAKE_TIMEOUT_MS)
+    this.handshakeTimer.unref?.()
+
+    socket.setNoDelay?.(true)
+    socket.on('data', (chunk) => this.onData(chunk))
+    socket.on('error', (error) => this.onSocketError(error))
+    socket.on('close', () => this.onSocketClose())
+
+    if (socket.connecting) socket.once('connect', () => this.start())
+    else this.start()
+  }
+
+  start() {
+    if (this.phase !== 'handshake' || this.closed) return
+    if (this.role === 'initiator') this.sendHello()
+    // responder waits for HELLO
+  }
+
+  // ---------------------------------------------------------------- handshake
+
+  sendHello() {
+    this.ephemeral = generateEphemeral()
+    const nonce = randomBytes(32)
+    const fields = {
+      t: 'hello',
+      v: PROTOCOL_VERSION,
+      fleetId: this.fleet.fleetId,
+      deviceId: this.identity.deviceId,
+      name: this.identity.name ?? 'device',
+      edPublic: this.identity.edPublic,
+      xPublic: this.identity.xPublic,
+      ephX: this.ephemeral.publicKey,
+      nonce: b64(nonce),
+      ts: Date.now(),
+      accountFingerprint: this.accountFingerprint ?? null,
+      pluginVersion: this.pluginVersion,
+      dshVersion: this.dshVersion,
+      capabilities: this.capabilities,
+    }
+    const proof = membershipProof({
+      fleetKey: this.fleet.fleetKey,
+      fleetId: this.fleet.fleetId,
+      deviceId: this.identity.deviceId,
+      edPublic: this.identity.edPublic,
+      xPublic: this.identity.xPublic,
+      accountFingerprint: this.accountFingerprint ?? null,
+    })
+    const signed = { ...fields, proof }
+    const sig = sign(null, Buffer.from(stableStringify(signed)), importPrivateKey(this.identity.edPrivate)).toString('base64url')
+    this.localFields = fields
+    this.writeLine({ ...signed, sig })
+  }
+
+  async onHello(message) {
+    const fields = this.validateIdentityMessage(message, 'hello')
+    if (fields === null) return
+    this.peer = this.peerFrom(fields)
+    if (!(await this.authorizePeer())) return
+
+    this.ephemeral = generateEphemeral()
+    const shared = diffieHellman({
+      privateKey: importPrivateKey(this.ephemeral.privateKeyPem),
+      publicKey: importPublicKey(fields.ephX),
+    })
+    const nonce = randomBytes(32)
+    const ackFields = {
+      t: 'hello.ack',
+      v: PROTOCOL_VERSION,
+      fleetId: this.fleet.fleetId,
+      deviceId: this.identity.deviceId,
+      name: this.identity.name ?? 'device',
+      edPublic: this.identity.edPublic,
+      xPublic: this.identity.xPublic,
+      ephX: this.ephemeral.publicKey,
+      nonce: b64(nonce),
+      ts: Date.now(),
+      accountFingerprint: this.accountFingerprint ?? null,
+      pluginVersion: this.pluginVersion,
+      dshVersion: this.dshVersion,
+      capabilities: this.capabilities,
+    }
+    const proof = membershipProof({
+      fleetKey: this.fleet.fleetKey,
+      fleetId: this.fleet.fleetId,
+      deviceId: this.identity.deviceId,
+      edPublic: this.identity.edPublic,
+      xPublic: this.identity.xPublic,
+      accountFingerprint: this.accountFingerprint ?? null,
+    })
+    const signed = { ...ackFields, proof }
+    const sig = sign(null, Buffer.from(stableStringify(signed)), importPrivateKey(this.identity.edPrivate)).toString('base64url')
+    this.localFields = ackFields
+    this.writeLine({ ...signed, sig })
+
+    const transcript = sha256(stableStringify({ hello: fields, ack: ackFields }))
+    this.deriveKeys(shared, transcript, 'responder')
+    this.enterFrames()
+    this.sendReady()
+  }
+
+  async onHelloAck(message) {
+    const fields = this.validateIdentityMessage(message, 'hello.ack')
+    if (fields === null) return
+    this.peer = this.peerFrom(fields)
+    if (!(await this.authorizePeer())) return
+
+    const shared = diffieHellman({
+      privateKey: importPrivateKey(this.ephemeral.privateKeyPem),
+      publicKey: importPublicKey(fields.ephX),
+    })
+    const transcript = sha256(stableStringify({ hello: this.localFields, ack: fields }))
+    this.deriveKeys(shared, transcript, 'initiator')
+    this.enterFrames()
+    this.sendReady()
+  }
+
+  validateIdentityMessage(message, kind) {
+    const fail = (reason) => {
+      this.fail('handshake-rejected', reason)
+      return null
+    }
+    if (!message || typeof message !== 'object') return fail(`${kind} is not an object`)
+    if (message.t !== kind) return fail(`expected ${kind}`)
+    if (message.v !== PROTOCOL_VERSION) return fail('protocol version mismatch')
+    if (message.pluginVersion !== this.pluginVersion) {
+      return fail(`plugin version mismatch: peer ${String(message.pluginVersion)} vs local ${this.pluginVersion}`)
+    }
+    if (message.dshVersion !== this.dshVersion) {
+      return fail(`harness version mismatch: peer ${String(message.dshVersion)} vs local ${this.dshVersion}`)
+    }
+    if (message.fleetId !== this.fleet.fleetId) return fail('fleet mismatch')
+    if (!isNonEmptyString(message.deviceId)) return fail('missing device id')
+    if (message.deviceId === this.identity.deviceId) return fail('peer is this device')
+    for (const key of ['edPublic', 'xPublic', 'ephX', 'nonce', 'proof', 'sig']) {
+      if (!isNonEmptyString(message[key])) return fail(`missing ${key}`)
+    }
+    if (typeof message.ts !== 'number' || Math.abs(Date.now() - message.ts) > MAX_CLOCK_SKEW_MS) {
+      return fail('clock skew too large')
+    }
+    if (this.expectedPeer?.deviceId !== undefined && message.deviceId !== this.expectedPeer.deviceId) {
+      return fail('unexpected device id')
+    }
+    if (this.expectedPeer?.edPublic !== undefined && message.edPublic !== this.expectedPeer.edPublic) {
+      return fail('device key changed')
+    }
+    if (this.expectedPeer?.xPublic !== undefined && message.xPublic !== this.expectedPeer.xPublic) {
+      return fail('device agreement key changed')
+    }
+    if (this.accountFingerprint !== null && this.accountFingerprint !== undefined) {
+      if ((message.accountFingerprint ?? null) !== this.accountFingerprint) return fail('account mismatch')
+    }
+
+    const { sig, ...signed } = message
+    let signatureOk = false
+    try {
+      signatureOk = verify(null, Buffer.from(stableStringify(signed)), importPublicKey(message.edPublic), Buffer.from(sig, 'base64url'))
+    } catch {
+      signatureOk = false
+    }
+    if (!signatureOk) return fail('invalid signature')
+
+    const proofOk = verifyMembershipProof(message.proof, {
+      fleetKey: this.fleet.fleetKey,
+      fleetId: this.fleet.fleetId,
+      deviceId: message.deviceId,
+      edPublic: message.edPublic,
+      xPublic: message.xPublic,
+      accountFingerprint: message.accountFingerprint ?? null,
+    })
+    if (!proofOk) return fail('invalid fleet membership proof')
+
+    return {
+      t: kind,
+      v: message.v,
+      fleetId: message.fleetId,
+      deviceId: message.deviceId,
+      name: message.name ?? 'device',
+      edPublic: message.edPublic,
+      xPublic: message.xPublic,
+      ephX: message.ephX,
+      nonce: message.nonce,
+      ts: message.ts,
+      accountFingerprint: message.accountFingerprint ?? null,
+      pluginVersion: message.pluginVersion,
+      dshVersion: message.dshVersion,
+      capabilities: Array.isArray(message.capabilities) ? message.capabilities : [],
+    }
+  }
+
+  peerFrom(fields) {
+    return {
+      deviceId: fields.deviceId,
+      name: fields.name,
+      edPublic: fields.edPublic,
+      xPublic: fields.xPublic,
+      accountFingerprint: fields.accountFingerprint ?? null,
+      pluginVersion: fields.pluginVersion,
+      dshVersion: fields.dshVersion,
+      capabilities: fields.capabilities ?? [],
+    }
+  }
+
+  async authorizePeer() {
+    if (typeof this.verifyPeer !== 'function') return true
+    try {
+      const allowed = await this.verifyPeer(this.peer)
+      if (!allowed) {
+        this.fail('peer-rejected', 'peer rejected by local policy')
+        return false
+      }
+      return true
+    } catch (error) {
+      this.fail('peer-rejected', `peer verification failed: ${String(error?.message ?? error)}`)
+      return false
+    }
+  }
+
+  deriveKeys(shared, transcript, role) {
+    const okm = Buffer.from(
+      hkdfSync('sha256', shared, transcript, Buffer.from('dsh-device-fleet/channel/v1'), 72),
+    )
+    const initiatorToResponderKey = okm.subarray(0, 32)
+    const initiatorToResponderPrefix = okm.subarray(32, 36)
+    const responderToInitiatorKey = okm.subarray(36, 68)
+    const responderToInitiatorPrefix = okm.subarray(68, 72)
+    if (role === 'initiator') {
+      this.sendKey = initiatorToResponderKey
+      this.sendPrefix = initiatorToResponderPrefix
+      this.recvKey = responderToInitiatorKey
+      this.recvPrefix = responderToInitiatorPrefix
+    } else {
+      this.sendKey = responderToInitiatorKey
+      this.sendPrefix = responderToInitiatorPrefix
+      this.recvKey = initiatorToResponderKey
+      this.recvPrefix = initiatorToResponderPrefix
+    }
+  }
+
+  enterFrames() {
+    this.phase = 'frames'
+    if (this.recvBuffer.length > 0) this.processFrames()
+  }
+
+  sendReady() {
+    if (this.readySent || this.closed) return
+    this.readySent = true
+    this.sendFrame({ t: FRAME.READY, v: PROTOCOL_VERSION, deviceId: this.identity.deviceId })
+    this.maybeAuthenticate()
+  }
+
+  onReadyFrame() {
+    this.readyReceived = true
+    this.maybeAuthenticate()
+  }
+
+  maybeAuthenticate() {
+    if (this.authenticated || !this.readySent || !this.readyReceived) return
+    this.authenticated = true
+    clearTimeout(this.handshakeTimer)
+    this.emit('ready', this.peer)
+  }
+
+  // ------------------------------------------------------------------- frames
+
+  writeLine(message) {
+    if (this.closed) return
+    this.socket.write(JSON.stringify(message) + '\n')
+  }
+
+  sendFrame(message) {
+    if (this.closed) throw new Error('secure channel is closed')
+    if (this.phase !== 'frames' || !this.sendKey) throw new Error('secure channel is not ready')
+    const plaintext = Buffer.from(JSON.stringify(message))
+    this.sendCounter += 1n
+    const nonce = Buffer.alloc(12)
+    this.sendPrefix.copy(nonce, 0)
+    nonce.writeBigUInt64BE(this.sendCounter, 4)
+    const cipher = createCipheriv('aes-256-gcm', this.sendKey, nonce)
+    cipher.setAAD(AAD)
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()])
+    const tag = cipher.getAuthTag()
+    const payload = Buffer.concat([ciphertext, tag])
+    const header = Buffer.alloc(4)
+    header.writeUInt32BE(payload.length)
+    this.socket.write(Buffer.concat([header, payload]))
+  }
+
+  onData(chunk) {
+    if (this.closed) return
+    this.recvBuffer = Buffer.concat([this.recvBuffer, chunk])
+    if (this.phase === 'handshake') this.processHandshake()
+    if (this.phase === 'frames') this.processFrames()
+  }
+
+  processHandshake() {
+    if (this.handshakeBusy) return
+    this.handshakeBusy = true
+    this.drainHandshake().finally(() => {
+      this.handshakeBusy = false
+      if (this.phase === 'frames' && !this.closed) this.processFrames()
+    })
+  }
+
+  async drainHandshake() {
+    while (this.phase === 'handshake' && !this.closed) {
+      const newline = this.recvBuffer.indexOf(0x0a)
+      if (newline < 0) return
+      const line = this.recvBuffer.subarray(0, newline).toString('utf8')
+      this.recvBuffer = this.recvBuffer.subarray(newline + 1)
+      let message
+      try {
+        message = JSON.parse(line)
+      } catch {
+        this.fail('handshake-rejected', 'invalid handshake JSON')
+        return
+      }
+      if (message.t === 'hello' && this.role === 'responder') {
+        try {
+          await this.onHello(message)
+        } catch (error) {
+          this.fail('handshake-error', `hello handling failed: ${String(error?.stack ?? error)}`)
+          return
+        }
+      } else if (message.t === 'hello.ack' && this.role === 'initiator') {
+        try {
+          await this.onHelloAck(message)
+        } catch (error) {
+          this.fail('handshake-error', `ack handling failed: ${String(error?.stack ?? error)}`)
+          return
+        }
+      } else {
+        this.fail('handshake-rejected', `unexpected handshake message ${String(message.t)}`)
+        return
+      }
+    }
+  }
+
+  processFrames() {
+    while (this.phase === 'frames' && !this.closed) {
+      if (this.recvBuffer.length < 4) return
+      const length = this.recvBuffer.readUInt32BE(0)
+      if (length <= 16 || length > MAX_FRAME_BYTES) {
+        this.fail('frame-invalid', `invalid frame length ${String(length)}`)
+        return
+      }
+      if (this.recvBuffer.length < 4 + length) return
+      const payload = this.recvBuffer.subarray(4, 4 + length)
+      this.recvBuffer = this.recvBuffer.subarray(4 + length)
+      let message
+      try {
+        message = this.openFrame(payload)
+      } catch {
+        this.fail('frame-invalid', 'frame authentication failed')
+        return
+      }
+      this.dispatch(message)
+    }
+  }
+
+  openFrame(payload) {
+    const tag = payload.subarray(payload.length - 16)
+    const ciphertext = payload.subarray(0, payload.length - 16)
+    this.recvCounter += 1n
+    const nonce = Buffer.alloc(12)
+    this.recvPrefix.copy(nonce, 0)
+    nonce.writeBigUInt64BE(this.recvCounter, 4)
+    const decipher = createDecipheriv('aes-256-gcm', this.recvKey, nonce)
+    decipher.setAAD(AAD)
+    decipher.setAuthTag(tag)
+    const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()])
+    return JSON.parse(plaintext.toString('utf8'))
+  }
+
+  dispatch(message) {
+    if (!message || typeof message !== 'object') return
+    if (message.t === FRAME.READY) {
+      this.onReadyFrame()
+      return
+    }
+    if (message.t === FRAME.PING) {
+      try {
+        this.sendFrame({ t: FRAME.PONG, v: PROTOCOL_VERSION })
+      } catch {
+        /* closing */
+      }
+      return
+    }
+    if (message.t === FRAME.PONG) return
+    if (!this.authenticated) {
+      this.fail('frame-before-ready', 'frame received before channel was ready')
+      return
+    }
+    this.emit('frame', message)
+  }
+
+  // ----------------------------------------------------------------- lifecycle
+
+  onSocketError(error) {
+    if (this.closed) return
+    this.emit('error', error)
+  }
+
+  onSocketClose() {
+    if (this.closed) return
+    this.closed = true
+    clearTimeout(this.handshakeTimer)
+    this.emit('close', this.failure)
+  }
+
+  fail(code, message) {
+    if (this.closed) return
+    const error = new Error(message)
+    error.code = code
+    this.failure = error
+    this.emit('error', error)
+    this.destroy()
+  }
+
+  destroy() {
+    if (this.closed) return
+    try {
+      this.socket.destroy()
+    } catch {
+      /* ignore */
+    }
+  }
+
+  close() {
+    this.destroy()
+  }
+}