dsh-remote-control-plugin 0.3.5 → 0.4.0

package/host/fabric.js

@@ -3,12 +3,49 @@ import dgram from 'node:dgram'
 import http from 'node:http'
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import path from 'node:path'
+import { sasCode, signPayload, verifyPayload } from './identity.js'
+import { createCipherPair, createBoxCipher, deriveEphemeralKey, deriveSessionKey, ephemeralPublicPem, generateEphemeralKeypair } from './crypto.js'
+import { mintEphemeral, verifyEphemeral } from './handshake.js'
+import { localCandidates } from './nat.js'
+import { createPuncher } from './punch.js'
+import { createP2pNode } from './p2p.js'
+import { selectLane } from './lane.js'
 
 const ANNOUNCE_KIND = 'dsh-remote/announce'
 const ANNOUNCE_INTERVAL_MS = 4000
 const PEER_TTL_MS = 15000
 const REQUEST_TTL_MS = 10 * 60 * 1000
 const CLOCK_SKEW_MS = 5 * 60 * 1000
+// Upload chunks carry up to 1 MiB of base64 (~1.4 MiB of JSON), above the
+// default body cap; the relay's own per-message cap stays at 2 MiB.
+const UPLOAD_BODY_BYTES = 4 * 1024 * 1024
+
+/** Capability scopes; an approval without an explicit list keeps all of them. */
+export const DEFAULT_SCOPES = [
+  'sessions:list',
+  'transcript:read',
+  'prompt:send',
+  'stop',
+  'config:read',
+  'config:write',
+  'files:write',
+]
+
+const SCOPE_BY_PATH = [
+  [/^\/peer\/sessions$/, () => 'sessions:list'],
+  [/^\/peer\/stream$/, () => 'transcript:read'],
+  [/^\/peer\/prompt$/, () => 'prompt:send'],
+  [/^\/peer\/cancel$/, () => 'stop'],
+  [/^\/peer\/session\/config$/, (method) => (method === 'GET' ? 'config:read' : 'config:write')],
+  [/^\/peer\/upload\//, () => 'files:write'],
+]
+
+function scopeFor(method, pathname) {
+  for (const [pattern, pick] of SCOPE_BY_PATH) {
+    if (pattern.test(pathname)) return pick(method)
+  }
+  return undefined
+}
 
 /**
  * Peer fabric: LAN discovery, one-time approval, and the authenticated
@@ -17,7 +54,23 @@ const CLOCK_SKEW_MS = 5 * 60 * 1000
  * Everything here is plain Node so it can be exercised without Cordis:
  * `sessions` is a small facade over the Host's session controller.
  */
-export function createFabric({ log, config, self, sessions, stateFile }) {
+export function createFabric({ log, config, self, sessions, stateFile, store, uploads, identity, limits = {} }) {
+  const approvalStore = store ?? createFileStore(stateFile, log)
+  const rate = new Map() // deviceId -> { count, resetAt }
+  const rateLimit = {
+    windowMs: limits.rateWindowMs ?? 10_000,
+    max: limits.rateMax ?? 120,
+  }
+  function allowCall(deviceId) {
+    const now = Date.now()
+    const entry = rate.get(deviceId)
+    if (!entry || entry.resetAt <= now) {
+      rate.set(deviceId, { count: 1, resetAt: now + rateLimit.windowMs })
+      return true
+    }
+    entry.count += 1
+    return entry.count <= rateLimit.max
+  }
   const peers = new Map() // deviceId -> peer record
   const requests = new Map() // requestId -> inbound approval request
   const outgoing = new Map() // deviceId -> { requestId, at }
@@ -27,14 +80,287 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
   let reaper
   let loaded = false
   let relay
+  const ciphers = new Map()
+  const seenNonces = new Map()
+
+  /** Reject a nonce already spent by this peer inside the clock window. */
+  function acceptNonce(deviceId, nonce) {
+    const now = Date.now()
+    let bucket = seenNonces.get(deviceId)
+    if (!bucket) { bucket = new Map(); seenNonces.set(deviceId, bucket) }
+    for (const [key, expiry] of bucket) if (expiry <= now) bucket.delete(key)
+    if (bucket.has(nonce)) return false
+    bucket.set(nonce, now + CLOCK_SKEW_MS)
+    return true
+  }
+
+  /**
+   * Per-call authentication: the device's Ed25519 key when the peer's key is
+   * pinned, otherwise the legacy shared-secret HMAC so 0.3.x peers keep working.
+   */
+  function authHeaders(peerDeviceId, method, pathname) {
+    const approval = approvals.get(peerDeviceId)
+    const me = currentIdentity()
+    const timestamp = String(Date.now())
+    if (approval?.publicKey && me?.ed25519?.privateKey) {
+      const nonce = randomBytes(12).toString('hex')
+      const payload = `${self().deviceId}\n${method}\n${pathname}\n${timestamp}\n${nonce}`
+      return {
+        'x-dsh-peer-id': self().deviceId,
+        'x-dsh-peer-ts': timestamp,
+        'x-dsh-peer-nonce': nonce,
+        'x-dsh-peer-alg': 'ed25519',
+        'x-dsh-peer-sig': signPayload(me.ed25519.privateKey, payload),
+      }
+    }
+    if (approval?.secret) {
+      return {
+        'x-dsh-peer-id': self().deviceId,
+        'x-dsh-peer-ts': timestamp,
+        'x-dsh-peer-sig': sign(approval.secret, self().deviceId, method, pathname, timestamp, ''),
+      }
+    }
+    return undefined
+  }
+
+  const currentIdentity = () => (typeof identity === 'function' ? identity() : identity)
+
+  const ephemerals = new Map() // peerDeviceId -> local X25519 private key
+  const rotating = new Set()
+
+  /** Mint this side's ephemeral message for one pairing attempt. */
+  function mintFor(peerDeviceId, pairCode) {
+    const me = currentIdentity()
+    if (!me?.ed25519?.privateKey) return undefined
+    const keypair = generateEphemeralKeypair()
+    ephemerals.set(peerDeviceId, keypair.privateKey)
+    const message = mintEphemeral(me, self().deviceId, pairCode, keypair)
+    return message
+  }
+
+  /** Session key: ephemeral+static when both sides agreed, else static-static. */
+  function sessionKeyFor(peerDeviceId, label) {
+    const me = currentIdentity()
+    const approval = approvals.get(peerDeviceId)
+    if (!me?.x25519?.privateKey || !approval?.agreementKey) return undefined
+    const ephemeralPrivate = ephemerals.get(peerDeviceId)
+    if (ephemeralPrivate && approval.peerEphemeral) {
+      try {
+        const key = deriveEphemeralKey({
+          ephemeralPrivate,
+          peerEphemeralPublicPem: approval.peerEphemeral,
+          staticPrivate: me.x25519.privateKey,
+          peerStaticPublicPem: approval.agreementKey,
+          myFingerprint: me.fingerprint,
+          peerFingerprint: approval.fingerprint,
+          label,
+        })
+        return key
+      } catch { /* fall back to static-static */ }
+    }
+    const fallback = deriveSessionKey({
+      privateKey: me.x25519.privateKey,
+      peerPublicKeyPem: approval.agreementKey,
+      myFingerprint: me.fingerprint,
+      peerFingerprint: approval.fingerprint,
+      label,
+    })
+    return fallback
+  }
+
+  function cipherFor(peerDeviceId) {
+    const me = currentIdentity()
+    if (!me?.x25519?.privateKey) return undefined
+    const approval = approvals.get(peerDeviceId)
+    if (!approval?.agreementKey || !approval?.fingerprint) return undefined
+    const cached = ciphers.get(peerDeviceId)
+    if (cached) return cached
+    try {
+      const key = sessionKeyFor(peerDeviceId, 'channel')
+      if (!key) return undefined
+      const side = String(self().deviceId) < String(peerDeviceId) ? 'a' : 'b'
+      const pair = createCipherPair(key, side)
+      ciphers.set(peerDeviceId, pair)
+      return pair
+    } catch (error) {
+      log.warn(`[remote-control] channel setup failed for ${peerDeviceId}: ${error?.message || error}`)
+      return undefined
+    }
+  }
+
+  const lanCiphers = new Map()
+  const p2pBoxes = new Map()
+  let p2pNode
+  let publicEndpoint
+
+  /** Sealed box for the p2p datagram lane, keyed per peer. */
+  function p2pBoxFor(deviceId) {
+    const key = sessionKeyFor(deviceId, 'p2p')
+    if (!key) return undefined
+    let box = p2pBoxes.get(deviceId)
+    if (!box) {
+      box = createBoxCipher(key)
+      p2pBoxes.set(deviceId, box)
+    }
+    return box
+  }
+
+  /** Per-peer AEAD pair for one direct transport lane (separate nonce space). */
+  function lanCipherFor(peerDeviceId, label = 'lan') {
+    const me = currentIdentity()
+    if (!me?.x25519?.privateKey) return undefined
+    const approval = approvals.get(peerDeviceId)
+    if (!approval?.agreementKey || !approval?.fingerprint) return undefined
+    const cacheKey = `${label}:${peerDeviceId}`
+    const cached = lanCiphers.get(cacheKey)
+    if (cached) return cached
+    try {
+      const key = sessionKeyFor(peerDeviceId, label)
+      if (!key) return undefined
+      const side = String(self().deviceId) < String(peerDeviceId) ? 'a' : 'b'
+      const pair = createCipherPair(key, side)
+      lanCiphers.set(cacheKey, pair)
+      return pair
+    } catch {
+      return undefined
+    }
+  }
+
+  /** Mint an ephemeral message without installing it as the live key yet. */
+  function mintDetached(pairCode) {
+    const me = currentIdentity()
+    if (!me?.ed25519?.privateKey) return undefined
+    const keypair = generateEphemeralKeypair()
+    return { privateKey: keypair.privateKey, message: mintEphemeral(me, self().deviceId, pairCode, keypair) }
+  }
+
+  /** Try to open a direct UDP path to one peer (both sides must call this). */
+  async function punchPeer(peerDeviceId) {
+    const approval = approvals.get(peerDeviceId)
+    if (!approval) return { ok: false, error: 'unknown-peer' }
+    const candidates = approval.candidates ?? []
+    const punchPort = approval.punchPort ?? 0
+    if (candidates.length === 0 || !punchPort) return { ok: false, error: 'no-candidates' }
+    if (!p2pNode) return { ok: false, error: 'p2p-unavailable' }
+    // The public mapping (STUN) is the only endpoint a NATed peer can answer on;
+    // LAN candidates are tried with the local punch port as a same-network path.
+    const targets = []
+    if (approval.publicEndpoint?.address) {
+      targets.push({ address: approval.publicEndpoint.address, port: approval.publicEndpoint.port })
+    }
+    for (const address of candidates) targets.push({ address, port: punchPort })
+    for (const target of targets) {
+      const result = await p2pNode.punch(target, peerDeviceId)
+      if (!result.ok) continue
+      approvals.set(peerDeviceId, { ...approval, punch: target })
+      await saveApprovals()
+      return { ok: true, address: target.address, port: target.port }
+    }
+    return { ok: false, error: 'no-pong' }
+  }
+
+  /** Rotate the ephemeral channel with one approved peer. */
+  async function rehandshakePeer(peerDeviceId) {
+    const peer = peers.get(peerDeviceId)
+    if (!peer) return { ok: false, error: 'unknown-peer' }
+    // Two simultaneous initiators would each install a different ephemeral and
+    // desynchronize the channel, so only one rotation may be in flight.
+    if (rotating.has(peerDeviceId)) return { ok: false, error: 'in-progress' }
+    rotating.add(peerDeviceId)
+    try {
+      const pairCode = self().pairCode ?? ''
+      const minted = mintDetached(pairCode)
+      if (!minted) return { ok: false, error: 'no-identity' }
+      // The request still travels over the current channel; the new key is
+      // installed only once the peer's signed reply verifies.
+      const result = await peerCall(peer, 'POST', '/peer/rehandshake', { ephemeral: minted.message })
+      if (!result.ok) return { ok: false, error: result.json?.error || result.error || 'rehandshake-failed' }
+      const theirs = result.json?.ephemeral
+      const approval = approvals.get(peerDeviceId)
+      if (!verifyEphemeral(approval?.publicKey ?? '', peerDeviceId, pairCode, theirs)) {
+        return { ok: false, error: 'bad-handshake' }
+      }
+      ephemerals.set(peerDeviceId, minted.privateKey)
+      approvals.set(peerDeviceId, { ...approval, peerEphemeral: theirs.publicPem, rotatedAt: Date.now() })
+      ciphers.delete(peerDeviceId)
+      for (const key of [...lanCiphers.keys()]) {
+        if (key.endsWith(`:${peerDeviceId}`)) lanCiphers.delete(key)
+      }
+      await saveApprovals()
+      return { ok: true }
+    } finally {
+      rotating.delete(peerDeviceId)
+    }
+  }
+
+  const security = {
+    seal(to, text) {
+      const pair = cipherFor(to)
+      if (!pair) return undefined
+      try { return pair.seal(text) } catch { return undefined }
+    },
+    open(from, packet) {
+      const pair = cipherFor(from)
+      if (!pair) return undefined
+      try { return pair.open(packet).toString('utf8') } catch (error) {
+        log.warn(`[remote-control] dropped an unauthenticated relay message from ${from}: ${error?.message || error}`)
+        return undefined
+      }
+    },
+  }
 
   const discoveryPort = config.discoveryPort
   const enabled = config.discovery !== false
 
   async function start() {
     await loadApprovals()
+
+    // The p2p lane must exist even when LAN discovery is disabled.
+    if (config.punchPort) {
+      try {
+        p2pNode = await createP2pNode({
+          localPort: config.port,
+          bindPort: config.punchPort,
+          selfDeviceId: self().deviceId,
+          log,
+          keyFor: (deviceId) => p2pBoxFor(deviceId),
+        })
+      } catch (error) {
+        log.warn(`[remote-control] could not open the p2p lane on ${config.punchPort}: ${error?.message || error}`)
+      }
+      // Learn this socket's public mapping so a NATed peer advertises something
+      // reachable. Without this only LAN addresses would be offered.
+      if (p2pNode && config.stunHost !== false) {
+        try {
+          const mapped = await p2pNode.mapped({
+            host: config.stunHost || 'stun.l.google.com',
+            port: config.stunPort ?? 19302,
+            timeoutMs: config.stunTimeoutMs ?? 1500,
+          })
+          if (mapped?.address) publicEndpoint = { address: mapped.address, port: mapped.port }
+        } catch { /* no STUN reachable; LAN candidates still work */ }
+      }
+    }
     if (!enabled) return
 
+    // Ephemeral keys live only in memory, so after a restart each approved peer
+    // is re-handshaked once reachable; until then the channel uses static-static.
+    const refreshMs = Number.isInteger(config.channelRefreshMs) ? config.channelRefreshMs : 2500
+    const refreshTimer = refreshMs > 0 ? setTimeout(() => {
+      for (const deviceId of approvals.keys()) {
+        // Only peers without an in-memory ephemeral need a rotation; this is
+        // the restart case, not a periodic re-key.
+        if (ephemerals.has(deviceId)) continue
+        // Deterministic initiator: only the lower device id starts an automatic
+        // rotation, so the two sides never rotate over each other.
+        if (String(self().deviceId) >= String(deviceId)) continue
+        const rotatedAt = approvals.get(deviceId)?.rotatedAt
+        if (rotatedAt && Date.now() - rotatedAt < 60_000) continue
+        rehandshakePeer(deviceId).catch(() => { /* peer offline */ })
+      }
+    }, refreshMs) : undefined
+    refreshTimer?.unref?.()
+
     const socket = dgram.createSocket({ type: 'udp4', reuseAddr: true })
     sockets.push(socket)
     socket.on('error', (error) => log.warn(`[remote-control] discovery socket: ${error?.message || error}`))
@@ -60,6 +386,9 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
   function stop() {
     clearInterval(announceTimer)
     clearInterval(reaper)
+    try { p2pNode?.close() } catch { /* already closed */ }
+    p2pNode = undefined
+    p2pBoxes.clear()
     for (const socket of sockets) {
       try { socket.close() } catch { /* ignore */ }
     }
@@ -150,13 +479,20 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
     if (loaded) return
     loaded = true
     try {
-      const raw = JSON.parse(await readFile(stateFile, 'utf8'))
+      const raw = await approvalStore.load()
       for (const [deviceId, entry] of Object.entries(raw?.peers ?? {})) {
         if (entry && typeof entry.secret === 'string') {
           approvals.set(deviceId, {
             deviceName: entry.deviceName ?? 'DSH device',
             secret: entry.secret,
             approvedAt: entry.approvedAt ?? Date.now(),
+            relay: entry.relay ?? '',
+            publicKey: entry.publicKey ?? '',
+            fingerprint: entry.fingerprint ?? '',
+            agreementKey: entry.agreementKey ?? '',
+            peerEphemeral: entry.peerEphemeral ?? '',
+            sas: entry.sas ?? '',
+            scopes: Array.isArray(entry.scopes) ? entry.scopes : [...DEFAULT_SCOPES],
           })
         }
       }
@@ -169,10 +505,9 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
     const peersObject = {}
     for (const [deviceId, entry] of approvals) peersObject[deviceId] = entry
     try {
-      await mkdir(path.dirname(stateFile), { recursive: true })
-      await writeFile(stateFile, JSON.stringify({ version: 1, peers: peersObject }, null, 2), { mode: 0o600 })
+      await approvalStore.save({ version: 1, peers: peersObject })
     } catch (error) {
-      log.warn(`[remote-control] could not persist ${stateFile}: ${error?.message || error}`)
+      log.warn(`[remote-control] could not persist approvals: ${error?.message || error}`)
     }
   }
 
@@ -184,11 +519,38 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
       if (!deviceId) return json(res, 400, { error: 'missing-device' })
       if (requests.size >= 20) return json(res, 429, { error: 'too-many-requests' })
       const requestId = randomBytes(16).toString('hex')
+      const claimedRelay = typeof body?.relay === 'string' ? body.relay : ''
+      const claimedPairCode = typeof body?.pairCode === 'string' ? body.pairCode : ''
+      const claimedFingerprint = typeof body?.fingerprint === 'string' ? body.fingerprint : ''
+      const claimedKey = typeof body?.publicKey === 'string' ? body.publicKey : ''
+      const known = approvals.get(deviceId)
+      const who = self()
+      const claimedEphemeral = body?.ephemeral
+      const ephemeralOk = verifyEphemeral(claimedKey, deviceId, claimedPairCode, claimedEphemeral)
+      const replyEphemeral = mintFor(deviceId, claimedPairCode)
       requests.set(requestId, {
         requestId,
         deviceId,
         deviceName: typeof body.deviceName === 'string' ? body.deviceName : 'DSH device',
         userId: typeof body.userId === 'string' ? body.userId : null,
+        relay: claimedRelay,
+        pairCode: claimedPairCode,
+        publicKey: claimedKey,
+        fingerprint: claimedFingerprint,
+        peerEphemeral: ephemeralOk ? claimedEphemeral.publicPem : '',
+        candidates: Array.isArray(body?.candidates) ? body.candidates.filter((entry) => typeof entry === 'string').slice(0, 16) : [],
+        punchPort: Number.isInteger(body?.punchPort) ? body.punchPort : 0,
+        publicEndpoint: body?.publicEndpoint && typeof body.publicEndpoint.address === 'string' && Number.isInteger(body.publicEndpoint.port)
+          ? { address: body.publicEndpoint.address, port: body.publicEndpoint.port }
+          : null,
+        replyEphemeral,
+        agreementKey: typeof body?.agreementKey === 'string' ? body.agreementKey : '',
+        // Both screens show these digits only when both keys and the invite
+        // nonce agree; a mismatch is a hard stop, not a warning.
+        sas: claimedFingerprint && who.fingerprint
+          ? sasCode(who.fingerprint, claimedFingerprint, claimedPairCode)
+          : '',
+        relayChanged: Boolean(known?.relay && claimedRelay && known.relay !== claimedRelay),
         address: req.socket?.remoteAddress ?? '',
         at: Date.now(),
         status: 'pending',
@@ -201,10 +563,26 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
   function helloStatus(res, requestId) {
     const request = requests.get(requestId)
     if (!request) return json(res, 404, { error: 'unknown-request' })
+    const who = self()
     if (request.status === 'approved') {
-      return json(res, 200, { status: 'approved', secret: request.secret, deviceName: self().deviceName })
+      return json(res, 200, {
+        status: 'approved',
+        // A peer that pinned a device key never needs the shared secret, and
+        // the relay would see this response in plaintext. Only legacy peers
+        // (no claimed public key) still receive one.
+        ...(request.publicKey ? {} : { secret: request.secret }),
+        deviceName: who.deviceName,
+        publicKey: who.publicKey ?? '',
+        fingerprint: who.fingerprint ?? '',
+        agreementKey: who.agreementKey ?? '',
+        ephemeral: request.replyEphemeral,
+        candidates: localCandidates().map((entry) => entry.address),
+        punchPort: config.punchPort ?? 0,
+        publicEndpoint: publicEndpoint ?? null,
+        sas: request.sas ?? '',
+      })
     }
-    return json(res, 200, { status: request.status })
+    return json(res, 200, { status: request.status, sas: request.sas ?? '' })
   }
 
   async function approveRequest(requestId) {
@@ -213,7 +591,22 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
     const secret = randomBytes(32).toString('hex')
     request.status = 'approved'
     request.secret = secret
-    approvals.set(request.deviceId, { deviceName: request.deviceName, secret, approvedAt: Date.now() })
+    approvals.set(request.deviceId, {
+      deviceName: request.deviceName,
+      secret,
+      approvedAt: Date.now(),
+      relay: request.relay ?? '',
+      publicKey: request.publicKey ?? '',
+      fingerprint: request.fingerprint ?? '',
+      agreementKey: request.agreementKey ?? '',
+      peerEphemeral: request.peerEphemeral ?? '',
+      candidates: Array.isArray(request.candidates) ? request.candidates : [],
+      punchPort: Number.isInteger(request.punchPort) ? request.punchPort : 0,
+      publicEndpoint: request.publicEndpoint ?? null,
+      secret: request.publicKey ? '' : request.secret,
+      sas: request.sas ?? '',
+      scopes: [...DEFAULT_SCOPES],
+    })
     await saveApprovals()
     const peer = peers.get(request.deviceId)
     if (peer) { peer.approved = true; peer.secret = secret }
@@ -241,6 +634,15 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
       deviceId: who.deviceId,
       deviceName: who.deviceName,
       userId: who.userId,
+      relay: who.relayUrl ?? '',
+      pairCode: who.pairCode ?? '',
+      publicKey: who.publicKey ?? '',
+      fingerprint: who.fingerprint ?? '',
+      agreementKey: who.agreementKey ?? '',
+      ephemeral: mintFor(peer.deviceId, who.pairCode ?? ''),
+      candidates: localCandidates().map((entry) => entry.address),
+      punchPort: config.punchPort ?? 0,
+      publicEndpoint: publicEndpoint ?? null,
     })
     if (!reply.ok || typeof reply.json?.requestId !== 'string') {
       return { ok: false, error: reply.json?.error || reply.error || 'hello-failed' }
@@ -258,11 +660,29 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
       if (!outgoing.has(peer.deviceId)) return
       const reply = await peerCall(peer, 'GET', `/peer/hello/${requestId}`)
       const status = reply.json?.status
-      if (status === 'approved' && typeof reply.json.secret === 'string') {
-        approvals.set(peer.deviceId, { deviceName: peer.deviceName, secret: reply.json.secret, approvedAt: Date.now() })
+      if (status === 'approved') {
+        const replyEphemeral = reply.json.ephemeral
+        const ephemeralOk = verifyEphemeral(reply.json.publicKey ?? '', peer.deviceId, self().pairCode ?? '', replyEphemeral)
+        approvals.set(peer.deviceId, {
+          deviceName: peer.deviceName,
+          secret: reply.json.secret ?? '',
+          approvedAt: Date.now(),
+          relay: relay?.url() ?? '',
+          publicKey: reply.json.publicKey ?? '',
+          fingerprint: reply.json.fingerprint ?? '',
+          agreementKey: reply.json.agreementKey ?? '',
+          peerEphemeral: ephemeralOk ? replyEphemeral.publicPem : '',
+          candidates: Array.isArray(reply.json.candidates) ? reply.json.candidates : [],
+          punchPort: Number.isInteger(reply.json.punchPort) ? reply.json.punchPort : 0,
+          publicEndpoint: reply.json.publicEndpoint ?? null,
+          sas: reply.json.sas ?? '',
+          scopes: [...DEFAULT_SCOPES],
+        })
+        peer.publicKey = reply.json.publicKey ?? ''
+        peer.sas = reply.json.sas ?? ''
         await saveApprovals()
         peer.approved = true
-        peer.secret = reply.json.secret
+        peer.secret = reply.json.secret ?? ''
         outgoing.delete(peer.deviceId)
         log.info(`[remote-control] ${peer.deviceName} approved this device`)
         return
@@ -285,42 +705,105 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
 
     const verdict = verifyPeer(req, url)
     if (!verdict.ok) return json(res, 403, { error: verdict.error })
+    if (!allowCall(verdict.deviceId)) return json(res, 429, { error: 'rate-limited' })
+    const requiredScope = scopeFor(req.method || 'GET', pathname)
+    if (requiredScope && Array.isArray(verdict.approval?.scopes) && !verdict.approval.scopes.includes(requiredScope)) {
+      return json(res, 403, { error: 'scope-denied', scope: requiredScope })
+    }
+
+    const viaHeader = String(req.headers['x-dsh-via'] || '')
+    const fromRelay = viaHeader === 'relay' || viaHeader === 'p2p'
+    // A pinned peer on the direct transport must use the sealed lane; relay
+    // traffic is already inside the relay AEAD envelope.
+    let lanePair
+    if (!fromRelay && verdict.approval?.publicKey && pathname !== '/peer/stream') {
+      if (String(req.headers['x-dsh-lane'] || '') !== 'sealed') {
+        return json(res, 403, { error: 'plaintext-not-allowed' })
+      }
+      lanePair = lanCipherFor(verdict.deviceId)
+      if (!lanePair) return json(res, 403, { error: 'no-channel' })
+    }
+    // One body read for every authenticated POST: the peer may have sealed it
+    // with the LAN channel, and every route needs the same decoded value.
+    let body = {}
+    if (req.method === 'POST') {
+      let incoming
+      try {
+        incoming = await readJson(req, UPLOAD_BODY_BYTES)
+      } catch {
+        return json(res, 400, { error: 'bad-body' })
+      }
+      if (incoming && typeof incoming === 'object' && typeof incoming.enc === 'string') {
+        if (!lanePair) return json(res, 403, { error: 'no-channel' })
+        try {
+          body = JSON.parse(lanePair.open(incoming.enc).toString('utf8'))
+        } catch (error) {
+          return json(res, 403, { error: 'bad-envelope' })
+        }
+      } else {
+        body = incoming ?? {}
+      }
+    }
+    const reply = lanePair
+      ? (status, value) => json(res, status, { enc: lanePair.seal(JSON.stringify(value)) })
+      : (status, value) => json(res, status, value)
 
+    if (pathname.startsWith('/peer/upload/') && uploads) {
+      const action = pathname.slice('/peer/upload/'.length)
+      const handler = uploads[action]
+      if (typeof handler !== 'function') return reply(404, { error: 'not-found' })
+      const payload = req.method === 'GET' ? Object.fromEntries(url.searchParams.entries()) : body
+      const result = await handler(payload)
+      return reply(result.status ?? 200, result)
+    }
+    if (pathname === '/peer/rehandshake' && req.method === 'POST') {
+      const peerMessage = body?.ephemeral
+      const mine = approvals.get(verdict.deviceId)
+      if (!peerMessage || !verifyEphemeral(mine?.publicKey ?? '', verdict.deviceId, self().pairCode ?? '', peerMessage)) {
+        return reply(400, { error: 'bad-handshake' })
+      }
+      const replyMessage = mintFor(verdict.deviceId, self().pairCode ?? '')
+      approvals.set(verdict.deviceId, { ...mine, peerEphemeral: peerMessage.publicPem })
+      ciphers.delete(verdict.deviceId)
+      for (const key of [...lanCiphers.keys()]) {
+        if (key.endsWith(`:${verdict.deviceId}`)) lanCiphers.delete(key)
+      }
+      await saveApprovals()
+      return reply(200, { ok: true, ephemeral: replyMessage })
+    }
     if (pathname === '/peer/session/config' && req.method === 'GET') {
       const sessionId = String(url.searchParams.get('sessionId') || '')
-      if (!sessionId) return json(res, 400, { error: 'missing-session' })
-      if (typeof sessions.config !== 'function') return json(res, 503, { error: 'config-unavailable' })
-      return json(res, 200, await sessions.config(sessionId))
+      if (!sessionId) return reply(400, { error: 'missing-session' })
+      if (typeof sessions.config !== 'function') return reply(503, { error: 'config-unavailable' })
+      return reply(200, await sessions.config(sessionId))
     }
     if (pathname === '/peer/session/config' && req.method === 'POST') {
-      const body = await readJson(req)
       const sessionId = typeof body?.sessionId === 'string' ? body.sessionId : ''
-      if (!sessionId) return json(res, 400, { error: 'missing-session' })
-      if (typeof sessions.applyConfig !== 'function') return json(res, 503, { error: 'config-unavailable' })
-      return json(res, 200, await sessions.applyConfig(sessionId, body))
+      if (!sessionId) return reply(400, { error: 'missing-session' })
+      if (typeof sessions.applyConfig !== 'function') return reply(503, { error: 'config-unavailable' })
+      return reply(200, await sessions.applyConfig(sessionId, body))
     }
     if (pathname === '/peer/sessions' && req.method === 'GET') {
       const value = await sessions.list()
-      return json(res, 200, { items: value.map((item) => ({ ...item, title: item.title })) })
+      return reply(200, { items: value.map((item) => ({ ...item, title: item.title })) })
     }
     if (pathname === '/peer/stream' && req.method === 'GET') {
       return streamSession(req, res, url)
     }
     if (pathname === '/peer/prompt' && req.method === 'POST') {
-      const body = await readJson(req)
       const sessionId = typeof body?.sessionId === 'string' ? body.sessionId : ''
       const text = typeof body?.text === 'string' ? body.text : ''
-      if (!sessionId || !text.trim()) return json(res, 400, { error: 'bad-request' })
-      const value = await sessions.prompt(sessionId, text)
-      return json(res, 200, value)
+      const attachments = Array.isArray(body?.attachments) ? body.attachments : []
+      if (!sessionId || (!text.trim() && attachments.length === 0)) return reply(400, { error: 'bad-request' })
+      const value = await sessions.prompt(sessionId, { text, attachments })
+      return reply(200, value)
     }
     if (pathname === '/peer/cancel' && req.method === 'POST') {
-      const body = await readJson(req)
       const sessionId = typeof body?.sessionId === 'string' ? body.sessionId : ''
-      if (!sessionId) return json(res, 400, { error: 'bad-request' })
-      return json(res, 200, sessions.cancel(sessionId))
+      if (!sessionId) return reply(400, { error: 'bad-request' })
+      return reply(200, sessions.cancel(sessionId))
     }
-    return json(res, 404, { error: 'not-found' })
+    return reply(404, { error: 'not-found' })
   }
 
   function verifyPeer(req, url) {
@@ -333,16 +816,37 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
     if (!/^\d{1,16}$/.test(timestamp) || Math.abs(Date.now() - Number(timestamp)) > CLOCK_SKEW_MS) {
       return { ok: false, error: 'stale-signature' }
     }
+    // A pinned device key retires the shared secret: the approval response that
+    // carried that secret crossed the relay in plaintext, so accepting HMAC
+    // afterwards would let anyone who saw it forge calls.
+    if (approval.publicKey && String(req.headers['x-dsh-peer-alg'] || '') !== 'ed25519') {
+      return { ok: false, error: 'legacy-auth-disabled' }
+    }
+    if (String(req.headers['x-dsh-peer-alg'] || '') === 'ed25519') {
+      if (!approval.publicKey) return { ok: false, error: 'no-device-key' }
+      const nonce = String(req.headers['x-dsh-peer-nonce'] || '')
+      if (!nonce) return { ok: false, error: 'missing-nonce' }
+      const payload = `${deviceId}\n${req.method || 'GET'}\n${url.pathname + url.search}\n${timestamp}\n${nonce}`
+      if (!verifyPayload(approval.publicKey, payload, signature)) return { ok: false, error: 'bad-signature' }
+      if (!acceptNonce(deviceId, nonce)) return { ok: false, error: 'replayed' }
+      return { ok: true, deviceId, approval }
+    }
     const expected = sign(approval.secret, deviceId, req.method || 'GET', url.pathname + url.search, timestamp, '')
     const actual = Buffer.from(signature, 'hex')
     const wanted = Buffer.from(expected, 'hex')
     if (actual.length !== wanted.length || !timingSafeEqual(actual, wanted)) return { ok: false, error: 'bad-signature' }
-    return { ok: true }
+    return { ok: true, deviceId, approval }
   }
 
   async function streamSession(req, res, url) {
     const sessionId = String(url.searchParams.get('sessionId') || '')
     if (!sessionId) return json(res, 400, { error: 'missing-session' })
+    // Frames use their own key space, so a stream can never desync the unary
+    // body counters.
+    const peerDeviceId = String(req.headers['x-dsh-peer-id'] || '')
+    const streamPair = String(req.headers['x-dsh-lane'] || '') === 'sealed' && peerDeviceId
+      ? lanCipherFor(peerDeviceId, 'lan-stream')
+      : undefined
     const controller = new AbortController()
     res.writeHead(200, {
       'content-type': 'text/event-stream; charset=utf-8',
@@ -366,7 +870,9 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
     try {
       for await (const frame of sessions.follow(sessionId, controller.signal)) {
         if (res.writableEnded || res.destroyed) break
-        res.write(`data: ${JSON.stringify(frame)}\n\n`)
+        const payload = JSON.stringify(frame)
+        const wire = streamPair ? JSON.stringify({ enc: streamPair.seal(payload) }) : payload
+        res.write(`data: ${wire}\n\n`)
       }
     } catch (error) {
       if (!controller.signal.aborted) {
@@ -386,11 +892,40 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
    * when the peer was discovered there, direct HTTP for a LAN peer.
    */
   async function peerCall(peer, method, pathname, body, secret) {
+    const approval = approvals.get(peer.deviceId)
+    const datagramLimit = 64 * 1024
+    const bodySize = body === undefined ? 0 : JSON.stringify(body).length
+    if (p2pNode && approval?.punch && bodySize <= datagramLimit) {
+      const auth = authHeaders(peer.deviceId, method, pathname) ?? {}
+      const result = await p2pNode.request(
+        { address: approval.punch.address, port: approval.punch.port },
+        peer.deviceId,
+        {
+          method,
+          path: pathname,
+          headers: { ...auth, accept: 'application/json', 'content-type': 'application/json' },
+          bodyText: body === undefined ? '' : JSON.stringify(body),
+        },
+      )
+      if (result.ok) {
+        peer.lastTransport = 'p2p'
+        let json = {}
+        try { json = result.message.bodyText ? JSON.parse(result.message.bodyText) : {} } catch { json = {} }
+        return { ok: result.message.status >= 200 && result.message.status < 300, status: result.message.status, json }
+      }
+      // A failed datagram path falls through to LAN and then the relay.
+    }
     if (peer.proto !== 'relay') {
-      const direct = await callRaw(peer, method, pathname, body, secret, self().deviceId)
-      // A direct LAN route can be silently blocked (firewall profile, VPN
-      // change). The relay is outbound-only, so fall back instead of failing.
-      if (!direct.error || !relay) return direct
+      const auth = authHeaders(peer.deviceId, method, pathname)
+      const pair = lanCipherFor(peer.deviceId)
+      const lane = pair
+        ? { seal: (value) => pair.seal(value), open: (packet) => pair.open(packet).toString('utf8') }
+        : undefined
+      const direct = await callRaw(peer, method, pathname, body, secret, self().deviceId, auth, lane)
+      if (!direct.error) {
+        peer.lastTransport = 'lan'
+        return direct
+      }
       const viaRelay = await relayCall(peer, method, pathname, body, secret)
       return viaRelay.ok || viaRelay.status !== 503 ? viaRelay : direct
     }
@@ -399,10 +934,14 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
 
   async function relayCall(peer, method, pathname, body, secret) {
     if (!relay) return { ok: false, status: 503, json: { error: 'relay-offline' } }
+    peer.lastTransport = 'relay'
     const callerId = self().deviceId
     const timestamp = String(Date.now())
     const headers = { accept: 'application/json' }
-    if (secret) {
+    const relayAuth = authHeaders(peer.deviceId, method, pathname)
+    if (relayAuth) {
+      Object.assign(headers, relayAuth)
+    } else if (secret) {
       headers['x-dsh-peer-id'] = callerId
       headers['x-dsh-peer-ts'] = timestamp
       headers['x-dsh-peer-sig'] = sign(secret, callerId, method, pathname, timestamp, '')
@@ -445,6 +984,30 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
     const target = `/peer/stream?sessionId=${encodeURIComponent(sessionId)}`
     const timestamp = String(Date.now())
     const callerId = self().deviceId
+    if (config.p2pStreams !== false && p2pNode && approval.punch) {
+      const auth = authHeaders(deviceId, 'GET', target) ?? {}
+      res.writeHead(200, {
+        'content-type': 'text/event-stream; charset=utf-8',
+        'cache-control': 'no-store, no-transform',
+        connection: 'keep-alive',
+        'x-accel-buffering': 'no',
+      })
+      const handle = p2pNode.openStream(
+        { address: approval.punch.address, port: approval.punch.port },
+        deviceId,
+        { path: target, headers: { ...auth, accept: 'text/event-stream' } },
+        {
+          onChunk: (chunk) => { try { res.write(chunk) } catch { /* client gone */ } },
+          onEnd: () => { try { res.end() } catch { /* ignore */ } },
+        },
+      )
+      if (!handle.ok) {
+        try { res.destroy() } catch { /* ignore */ }
+        return
+      }
+      peer.lastTransport = 'p2p'
+      return
+    }
     if (peer.proto === 'relay') {
       if (!relay) {
         json(res, 503, { error: 'relay-offline' })
@@ -457,16 +1020,21 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
           'x-dsh-peer-id': callerId,
           'x-dsh-peer-ts': timestamp,
           'x-dsh-peer-sig': sign(approval.secret, callerId, 'GET', target, timestamp, ''),
+          ...(authHeaders(peer.deviceId, 'GET', target) ?? {}),
         },
       }, res)
       return
     }
+    const streamPair = lanCipherFor(peer.deviceId, 'lan-stream')
+    const streamAuth = authHeaders(peer.deviceId, 'GET', target)
     const streamHeaders = {
       accept: 'text/event-stream',
       'x-dsh-peer-id': callerId,
       'x-dsh-peer-ts': timestamp,
       'x-dsh-peer-sig': sign(approval.secret, callerId, 'GET', target, timestamp, ''),
+      ...(streamAuth ?? {}),
     }
+    if (streamPair) streamHeaders['x-dsh-lane'] = 'sealed'
     const upstream = http.request({
       host: peer.address,
       port: peer.port,
@@ -480,7 +1048,35 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
         connection: 'keep-alive',
         'x-accel-buffering': 'no',
       })
-      response.pipe(res)
+      if (!streamPair) {
+        response.pipe(res)
+        response.on('end', () => { try { res.end() } catch { /* ignore */ } })
+        return
+      }
+      // Decrypt each sealed frame before handing it to the local client.
+      response.setEncoding('utf8')
+      let buffer = ''
+      response.on('data', (chunk) => {
+        buffer += chunk
+        let index
+        while ((index = buffer.indexOf('\n\n')) >= 0) {
+          const event = buffer.slice(0, index)
+          buffer = buffer.slice(index + 2)
+          const line = event.split('\n').find((entry) => entry.startsWith('data: '))
+          if (line) {
+            try {
+              const parsed = JSON.parse(line.slice(6))
+              if (parsed && typeof parsed.enc === 'string') {
+                res.write(`data: ${streamPair.open(parsed.enc).toString('utf8')}\n\n`)
+                continue
+              }
+            } catch {
+              continue
+            }
+          }
+          res.write(`${event}\n\n`)
+        }
+      })
       response.on('end', () => { try { res.end() } catch { /* ignore */ } })
     })
     upstream.on('error', () => {
@@ -505,8 +1101,20 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
     callPeer,
     proxyStream,
     handlePeer,
+    rehandshake: rehandshakePeer,
+    attemptPunch: punchPeer,
+    async clearPunch(peerDeviceId) {
+      const approval = approvals.get(peerDeviceId)
+      if (!approval) return { ok: false, error: 'unknown-peer' }
+      const next = { ...approval }
+      delete next.punch
+      approvals.set(peerDeviceId, next)
+      await saveApprovals()
+      return { ok: true }
+    },
     setRelay(link) {
       relay = link
+      if (link && typeof link.setSecurity === 'function') link.setSecurity(security)
       if (!link) {
         // Without a relay every relay-only peer is unreachable; keeping it
         // would make each call fail with a misleading 503.
@@ -515,6 +1123,20 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
         }
       }
     },
+    setScopes(deviceId, scopes) {
+      const approval = approvals.get(deviceId)
+      if (!approval) return { ok: false, error: 'unknown-device' }
+      const next = Array.isArray(scopes) ? scopes.filter((scope) => DEFAULT_SCOPES.includes(scope)) : []
+      approvals.set(deviceId, { ...approval, scopes: next })
+      saveApprovals().catch(() => {})
+      return { ok: true, scopes: next }
+    },
+    revoke(deviceId) {
+      if (!approvals.delete(deviceId)) return { ok: false, error: 'unknown-device' }
+      ciphers.delete(deviceId)
+      saveApprovals().catch(() => {})
+      return { ok: true }
+    },
 
     snapshot() {
       syncRelayPeers()
@@ -531,6 +1153,16 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
           approved: approvals.has(peer.deviceId),
           connecting: outgoing.has(peer.deviceId),
           transport: peer.proto === 'relay' ? 'relay' : 'lan',
+          relay: approvals.get(peer.deviceId)?.relay ?? '',
+          fingerprint: approvals.get(peer.deviceId)?.fingerprint ?? '',
+          forwardSecrecy: Boolean(approvals.get(peer.deviceId)?.peerEphemeral && ephemerals.has(peer.deviceId)),
+          lane: selectLane({ sameLan: peer.proto !== 'relay', punched: Boolean(approvals.get(peer.deviceId)?.punch), relayAvailable: Boolean(relay) }),
+          transport: peer.lastTransport ?? (peer.proto === 'relay' ? 'relay' : 'lan'),
+          punch: approvals.get(peer.deviceId)?.punch ?? null,
+          candidates: Array.isArray(approvals.get(peer.deviceId)?.candidates) ? approvals.get(peer.deviceId).candidates.length : 0,
+          punchPort: peer.punchPort ?? 0,
+          sas: approvals.get(peer.deviceId)?.sas ?? '',
+          scopes: approvals.get(peer.deviceId)?.scopes ?? [],
         })),
         requests: [...requests.values()]
           .filter((request) => request.status === 'pending')
@@ -540,6 +1172,11 @@ export function createFabric({ log, config, self, sessions, stateFile }) {
             deviceName: request.deviceName,
             userId: request.userId,
             at: request.at,
+            relay: request.relay ?? '',
+            pairCode: request.pairCode ?? '',
+            sas: request.sas ?? '',
+            fingerprint: request.fingerprint ?? '',
+            relayChanged: Boolean(request.relayChanged),
           })),
       }
     },
@@ -554,15 +1191,21 @@ function sign(secret, deviceId, method, pathname, timestamp, body) {
     .digest('hex')
 }
 
-function callRaw(peer, method, pathname, body, secret, callerId) {
+function callRaw(peer, method, pathname, body, secret, callerId, extraHeaders, lane) {
   return new Promise((resolve) => {
-    const text = body === undefined ? '' : JSON.stringify(body)
+    let text = body === undefined ? '' : JSON.stringify(body)
+    if (lane && body !== undefined) {
+      try { text = JSON.stringify({ enc: lane.seal(text) }) } catch { /* keep plaintext */ }
+    }
     const headers = { accept: 'application/json' }
     if (text) {
       headers['content-type'] = 'application/json'
       headers['content-length'] = Buffer.byteLength(text)
     }
-    if (secret && callerId) {
+    if (extraHeaders) {
+      Object.assign(headers, extraHeaders)
+      if (lane) headers['x-dsh-lane'] = 'sealed'
+    } else if (secret && callerId) {
       const timestamp = String(Date.now())
       headers['x-dsh-peer-id'] = callerId
       headers['x-dsh-peer-ts'] = timestamp
@@ -583,6 +1226,9 @@ function callRaw(peer, method, pathname, body, secret, callerId) {
       res.on('end', () => {
         let parsed
         try { parsed = data ? JSON.parse(data) : {} } catch { parsed = {} }
+        if (lane && parsed && typeof parsed.enc === 'string') {
+          try { parsed = JSON.parse(lane.open(parsed.enc)) } catch { parsed = { error: 'bad-envelope' } }
+        }
         resolve({ ok: res.statusCode >= 200 && res.statusCode < 300, status: res.statusCode, json: parsed })
       })
     })
@@ -592,13 +1238,19 @@ function callRaw(peer, method, pathname, body, secret, callerId) {
   })
 }
 
-function readJson(req) {
+function readJson(req, maxBytes = 1024 * 1024) {
   return new Promise((resolve, reject) => {
+    const declared = Number(req.headers?.['content-length'])
+    if (Number.isFinite(declared) && declared > maxBytes) {
+      reject(new Error('too large'))
+      req.destroy()
+      return
+    }
     const chunks = []
     let size = 0
     req.on('data', (chunk) => {
       size += chunk.length
-      if (size > 1024 * 1024) { reject(new Error('too large')); req.destroy(); return }
+      if (size > maxBytes) { reject(new Error('too large')); req.destroy(); return }
       chunks.push(chunk)
     })
     req.on('end', () => {
@@ -619,6 +1271,25 @@ function json(res, status, value) {
   res.end(body)
 }
 
+function createFileStore(file, log) {
+  return {
+    async load() {
+      try { return JSON.parse(await readFile(file, 'utf8')) } catch (error) {
+        if (error?.code !== 'ENOENT') log.warn(`[remote-control] could not read ${file}: ${error?.message || error}`)
+        return null
+      }
+    },
+    async save(value) {
+      try {
+        await mkdir(path.dirname(file), { recursive: true })
+        await writeFile(file, JSON.stringify(value, null, 2), { mode: 0o600 })
+      } catch (error) {
+        log.warn(`[remote-control] could not persist ${file}: ${error?.message || error}`)
+      }
+    },
+  }
+}
+
 function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }