dsh-remote-control-plugin 0.3.6 → 0.4.1

package/INSTALL.md

@@ -4,12 +4,12 @@ Published as `dsh-remote-control-plugin`. Self-contained: no dependencies, no bu
 
 ## Install
 
-Web GUI: **Plugins → Add plugin**, enter `dsh-remote-control-plugin@0.3.6`, keep the official npm
+Web GUI: **Plugins → Add plugin**, enter `dsh-remote-control-plugin@0.4.1`, keep the official npm
 registry selected, then **Install** and **Enable now**. Restart DSH.
 
 From a chat (Standard or Creator preset — PTC disables `tool-plugin-manager`):
 
-> Install the DSH plugin bundle `dsh-remote-control-plugin@0.3.6` with plugin_manager.
+> Install the DSH plugin bundle `dsh-remote-control-plugin@0.4.1` with plugin_manager.
 
 ## Connect two machines
 
@@ -27,7 +27,8 @@ Same-LAN machines need no relay. No reachable machine? Run
 - Approvals live in `$DSH_HOME/remote-control-peers.json`; delete it to revoke.
 - Relay and control API share one port (default `57330`).
 - Peer traffic is signed but not encrypted; use a private network or TLS in front.
-- 0.3.6 fixes: ordered transcript chunks, hosted relay persistence, stale
+- 0.4.1 fixes: ordered transcript chunks, hosted relay persistence, stale
   relay peer pruning, relay fallback when a direct LAN route is blocked, a client
   module id that matches the package name, and a Devices config row for the
-  remote session's model, permission preset, and plan mode.
+  remote session's model, permission preset, and plan mode. It also adds peer
+  file uploads (chunked, resumable, stored through the Host attachment service).

package/README.md

@@ -15,19 +15,29 @@ Both drive `ctx.sessionController` in-process, so neither depends on the GUI's b
 
 ## How device trust works
 
-1. Each Host announces itself on UDP `discoveryPort` with its device id, display name, and
-   account id (when signed in).
-2. To control a peer, this Host sends `POST /peer/hello`. The **target** shows a pending
-   request in its own Devices panel; nothing is granted until a person there presses **Allow**.
-3. On approval the target issues a random per-peer secret. Every later call is signed
-   `HMAC-SHA256(secret, deviceId + method + path + timestamp + body)`, valid for 5 minutes of
-   clock skew.
-4. Approvals persist in `$DSH_HOME/remote-control-peers.json`. Deleting that file revokes
-   every device.
+1. Each Host generates a device identity once: an Ed25519 signing key and an X25519 agreement
+   key, stored as a credential-store record (a `0600` file only as a fallback). The fingerprint
+   is derived from the public key.
+2. Hosts announce themselves on UDP `discoveryPort` with device id, display name, and account id
+   (when signed in).
+3. To control a peer, this Host sends `POST /peer/hello` carrying its public key, fingerprint,
+   agreement key and a signed ephemeral key. The **target** shows a pending request in its own
+   Devices panel; nothing is granted until a person there presses **Allow** and the six-digit
+   short authentication string (SAS, derived from both fingerprints and the invite nonce) matches
+   on both screens.
+4. On approval the peer keys are pinned. Later calls carry an **Ed25519 signature** over method,
+   path, timestamp and a fresh nonce, with a five-minute skew window and a replay cache. The
+   legacy shared-secret HMAC is retired as soon as a key is pinned, because the approval response
+   that carried that secret crossed the relay in plaintext.
+5. Each approval records its scope list (`sessions:list`, `transcript:read`, `prompt:send`,
+   `stop`, `config:read`, `config:write`, `files:write`), the fingerprint, the agreement key and
+   the relay used. Scope edits and **Revoke** take effect immediately; revoking also drops the
+   cached keys.
+6. Approvals persist as credential-store grants; deleting the record revokes every device.
 
 There is deliberately no "same account implies trust" shortcut: two devices holding grants for
-the same account share no secret, so account id alone cannot authenticate a peer. The panel
-shows the account id of each candidate and flags a different account, but a person approves.
+the same account share no secret, so account id alone cannot authenticate a peer. The panel shows
+the account id of each candidate and flags a different account, but a person approves.
 
 ## Across networks (relay)
 
@@ -52,10 +62,32 @@ Host it on a VPS, NAS, or any always-on machine, put it behind TLS or a VPN, and
 `http://host:8787 <workspace key>` into every device.
 
 Either way the workspace key never leaves the devices: the relay only receives its SHA-256 as a
-group id. It forwards opaque `/peer/*` calls that stay signed end to end, so a compromised relay
-can drop or delay traffic but cannot forge a control command. Group membership alone grants
-nothing — the target still requires the one-time approval before any session call is accepted.
-Treat the relay as private: whoever holds the group id can join the group and *request* access.
+group id. It forwards opaque `/peer/*` calls, and after pairing every message is sealed end to
+end, so a compromised relay sees ciphertext and can only drop or delay traffic. Group membership
+alone grants nothing — the target still requires the one-time approval before any session call is
+accepted. Treat the relay as private: whoever holds the group id can join the group and *request*
+access.
+
+### Encryption
+
+Paired devices agree a session key with X25519 (ephemeral mixed with static when both sides
+completed the pairing handshake) → HKDF-SHA256 → ChaCha20-Poly1305. The relay envelope seals every
+message; on a direct LAN lane the request body and reply are sealed with a separate per-transport
+key, and transcript frames with another. Plaintext exists only during bootstrap: the `hello`
+request and the approval response that carries the peer's public keys.
+
+A peer that pinned an identity but has no agreement key is **refused** over the relay
+(`plaintext-refused`) rather than silently downgraded; `allowPlaintextFallback: true` opts out.
+Peers approved before identity keys existed keep the legacy HMAC path until they are re-approved.
+
+### Lane ladder
+
+Calls are attempted in order, each with its own budget: punched P2P (`p2pTimeoutMs`) → direct LAN
+(`directTimeoutMs`) → relay. A blocked direct lane is parked per peer for `routeBlockMs` and then
+retried as soon as fresh discovery evidence arrives. Latency-sensitive reads (`sessions`, session
+config) race the relay against the direct lane so only the first call after a network change pays
+a penalty; writes stay strictly ordered so a prompt can never run twice. `/state` reports `lane`,
+`transport`, `timing` and `blocked` per peer.
 
 ## Configuration
 
@@ -78,6 +110,13 @@ Defaults work on a LAN. Override the row in `$DSH_HOME/profiles/<profile>/cordis
     cookieDays: 30
     defaultCwd: ''
     tls: { certFile: '', keyFile: '' }
+    directTimeoutMs: 1000        # budget for one direct LAN call before fallback
+    streamConnectTimeoutMs: 2500 # budget for direct stream headers before fallback
+    p2pTimeoutMs: 800            # budget for the punched lane per call
+    routeBlockMs: 60000          # how long a failed lane stays parked
+    punchPort: 57332             # UDP lane; also needs an inbound UDP firewall rule
+    stunHost: stun.l.google.com  # or false to skip public mapping discovery
+    allowPlaintextFallback: false # refuse rather than downgrade a pinned peer
 ```
 
 The browser page and the peer API share the listener. When `host` is a wildcard, any IP literal
@@ -88,10 +127,20 @@ come from loopback.
 ## Threat model / limits
 
 - Approval is manual on purpose. A peer on the LAN can prompt for access; it cannot grant it.
+  Compare the six-digit SAS on both screens, and check the fingerprint when in doubt.
 - Prompts sent from a peer run with this Host's tools and permissions. Approve devices you
-  control.
-- Peer transport is plain HTTP. The peer secret crosses the LAN once, at approval time. Use a
-  private network or VPN, or set `tls` and front the port with a proxy.
+  control, and narrow scopes afterwards if a device only needs to read sessions.
+- Transport is encrypted: sealed bodies/replies and transcript frames on a direct lane, an AEAD
+  envelope over the relay. The relay sees ids, timing and ciphertext.
+- Legacy fallback: a peer approved before identity keys existed has no pinned key and still uses
+  the shared-secret HMAC in plaintext; a peer with a pinned identity but no agreement key is
+  refused over the relay unless `allowPlaintextFallback: true`. Re-approve to upgrade both.
+- Forward secrecy is per session: ephemeral keys live in memory and are re-established by the
+  startup re-handshake, so a restart briefly degrades to static-static agreement.
+- The construction is IK-shaped but **not Noise**: no protocol-name hash, no full handshake
+  transcript.
+- Uploads are capped at 25 MB per file and 100 MB per session, with a MIME allowlist; bytes only
+  enter the Host attachment store, never a caller-supplied path.
 - The pairing code protects the browser page only; it is printed at activation and stored in
   `$DSH_HOME/remote-control.json`.
 - Approvals that arrive while no Devices panel is open stay pending for up to 10 minutes.

package/client.js

@@ -126,6 +126,8 @@ window.__ModuleLoader__.load({
       const [live, setLive] = useState('')
       const [running, setRunning] = useState(false)
       const [draft, setDraft] = useState('')
+      const [pendingFiles, setPendingFiles] = useState([])
+      const [uploading, setUploading] = useState(null)
       const [error, setError] = useState(null)
       const [streamState, setStreamState] = useState('connecting')
       const [attempt, setAttempt] = useState(0)
@@ -197,18 +199,54 @@ window.__ModuleLoader__.load({
         if (node) node.scrollTop = node.scrollHeight
       }, [entries, live])
 
+      const addFiles = useCallback((list) => {
+        const files = Array.from(list ?? []).filter((file) => file && typeof file.size === 'number')
+        if (files.length > 0) setPendingFiles((current) => [...current, ...files])
+      }, [])
+
+      const dropFiles = useCallback((event) => {
+        event.preventDefault()
+        addFiles(event.dataTransfer?.files)
+      }, [addFiles])
+
       const send = useCallback(async () => {
         const text = draft.trim()
-        if (!text || !peerId || !sessionId) return
+        const pending = pendingFiles
+        if ((!text && pending.length === 0) || !peerId || !sessionId) return
         setDraft('')
         setError(null)
         try {
-          await api(`/remote-control/api/peer/${encodeURIComponent(peerId)}/prompt`, { sessionId, text })
+          const sent = []
+          for (const file of pending) {
+            setUploading({ name: file.name, progress: 0 })
+            const init = await api('/remote-control/api/upload/init', {
+              sessionId,
+              name: file.name || 'file',
+              size: file.size,
+              mediaType: file.type || 'application/octet-stream',
+            })
+            const uploadId = init?.uploadId
+            if (!uploadId) throw new Error('The device refused the upload.')
+            const chunkSize = 512 * 1024
+            for (let offset = 0, index = 0; offset < file.size; offset += chunkSize, index += 1) {
+              const bytes = new Uint8Array(await file.slice(offset, offset + chunkSize).arrayBuffer())
+              let binary = ''
+              for (let i = 0; i < bytes.length; i += 1) binary += String.fromCharCode(bytes[i])
+              await api('/remote-control/api/upload/chunk', { uploadId, index, data: btoa(binary) })
+              setUploading({ name: file.name, progress: Math.min(1, (offset + chunkSize) / Math.max(1, file.size)) })
+            }
+            const committed = await api('/remote-control/api/upload/commit', { uploadId })
+            if (committed?.attachment) sent.push(committed.attachment)
+          }
+          setUploading(null)
+          setPendingFiles([])
+          await api(`/remote-control/api/peer/${encodeURIComponent(peerId)}/prompt`, { sessionId, text, attachments: sent })
         } catch (failure) {
+          setUploading(null)
           setDraft(text)
           setError(failure.message)
         }
-      }, [draft, peerId, sessionId])
+      }, [draft, pendingFiles, peerId, sessionId])
 
       const stop = useCallback(async () => {
         try {
@@ -330,7 +368,29 @@ window.__ModuleLoader__.load({
           live ? h('div', { style: { ...S.bubble, ...S.assistantBubble, opacity: 0.85 } }, live) : null,
         ),
         configBar,
-        h('div', { style: S.composer },
+        h('div', { style: S.composer, onDragOver: (event) => event.preventDefault(), onDrop: dropFiles },
+          pendingFiles.length > 0 || uploading
+            ? h('div', { style: { display: 'flex', flexWrap: 'wrap', gap: 6, alignItems: 'center', marginBottom: 6 } },
+                pendingFiles.map((file, index) => h('span', {
+                  key: `${file.name}-${index}`,
+                  style: {
+                    display: 'inline-flex', gap: 6, alignItems: 'center', padding: '2px 8px',
+                    borderRadius: 999, background: 'rgba(127,127,127,0.18)', fontSize: 12,
+                  },
+                },
+                  `${file.name} · ${Math.max(1, Math.round(file.size / 1024))} KB`,
+                  h('button', {
+                    type: 'button',
+                    title: 'Remove',
+                    style: { border: 'none', background: 'transparent', cursor: 'pointer', color: 'inherit', padding: 0 },
+                    onClick: () => setPendingFiles((current) => current.filter((_, position) => position !== index)),
+                  }, '✕'),
+                )),
+                uploading
+                  ? h('span', { style: { fontSize: 12, opacity: 0.8 } }, `Uploading ${uploading.name} ${Math.round(uploading.progress * 100)}%`)
+                  : null,
+              )
+            : null,
           h('textarea', {
             style: S.input,
             rows: 1,
@@ -341,8 +401,22 @@ window.__ModuleLoader__.load({
               if (event.key === 'Enter' && !event.shiftKey) { event.preventDefault(); send() }
             },
           }),
+          h('label', { style: { ...S.button, cursor: 'pointer' }, title: 'Attach files' },
+            'Attach',
+            h('input', {
+              type: 'file',
+              multiple: true,
+              style: { display: 'none' },
+              onChange: (event) => { addFiles(event.target.files); event.target.value = '' },
+            }),
+          ),
           running ? h('button', { type: 'button', style: { ...S.button, ...S.danger }, onClick: stop }, 'Stop') : null,
-          h('button', { type: 'button', style: { ...S.button, ...S.primary }, onClick: send, disabled: !draft.trim() }, 'Send'),
+          h('button', {
+            type: 'button',
+            style: { ...S.button, ...S.primary },
+            onClick: send,
+            disabled: uploading !== null || (!draft.trim() && pendingFiles.length === 0),
+          }, uploading ? 'Uploading…' : 'Send'),
         ),
       )
     }
@@ -401,6 +475,7 @@ window.__ModuleLoader__.load({
       const [relayOpen, setRelayOpen] = useState(false)
       const [relayUrl, setRelayUrl] = useState('')
       const [relayKey, setRelayKey] = useState('')
+      const [reachability, setReachability] = useState(null)
 
       const refresh = useCallback(async () => {
         try {
@@ -440,6 +515,18 @@ window.__ModuleLoader__.load({
         refresh()
       }, [refresh])
 
+      const revoke = useCallback(async (deviceId) => {
+        setBusy(deviceId)
+        try {
+          await api('/remote-control/api/revoke', { deviceId })
+          setOpenPeer(null)
+        } catch (failure) {
+          setError(failure.message)
+        }
+        setBusy(null)
+        refresh()
+      }, [refresh])
+
       const open = useCallback(async (peer) => {
         setOpenPeer(peer)
         setSessions(null)
@@ -477,7 +564,8 @@ window.__ModuleLoader__.load({
         setBusy('relay')
         setError(null)
         try {
-          await api('/remote-control/api/relay/host', { enabled: true })
+          const value = await api('/remote-control/api/relay/host', { enabled: true })
+          if (value?.reachability) setReachability(value.reachability)
         } catch (failure) {
           setError(failure.message)
         }
@@ -488,10 +576,23 @@ window.__ModuleLoader__.load({
       const stopHosting = useCallback(async () => {
         setBusy('relay')
         try { await api('/remote-control/api/relay/host', { enabled: false }) } catch (failure) { setError(failure.message) }
+        setReachability(null)
         setBusy(null)
         refresh()
       }, [refresh])
 
+      const checkReachability = useCallback(async () => {
+        setBusy('reach')
+        setError(null)
+        try {
+          const value = await api('/remote-control/api/relay/reachability')
+          setReachability(value)
+        } catch (failure) {
+          setError(failure.message)
+        }
+        setBusy(null)
+      }, [])
+
       const clearRelay = useCallback(async () => {
         setBusy('relay')
         try { await api('/remote-control/api/relay/clear', {}) } catch (failure) { setError(failure.message) }
@@ -526,6 +627,13 @@ window.__ModuleLoader__.load({
               ? h('div', null,
                 h('div', { style: { ...S.meta, marginBottom: '6px' } },
                   'This device is hosting the relay. Paste this invite into the other device’s Relay panel.'),
+                relay.invite
+                  ? h('img', {
+                    alt: 'Invite QR code',
+                    src: `/remote-control/api/qr?text=${encodeURIComponent(relay.invite)}`,
+                    style: { width: '184px', height: '184px', marginBottom: '10px', background: '#fff', borderRadius: '8px', padding: '6px' },
+                  })
+                  : null,
                 h('div', { style: { display: 'flex', gap: '8px', flexWrap: 'wrap', alignItems: 'center' } },
                   h('input', {
                     style: { ...S.field, flex: 1, minWidth: '260px' },
@@ -542,6 +650,20 @@ window.__ModuleLoader__.load({
                 ),
                 h('div', { style: { ...S.meta, marginTop: '6px' } },
                   `Reachable at ${(relay.urls || []).join(', ') || 'this machine'} — forward that port (or set publicUrl) so other networks can reach it.`),
+                h('div', { style: { display: 'flex', gap: '8px', flexWrap: 'wrap', alignItems: 'center', marginTop: '8px' } },
+                  h('button', {
+                    type: 'button',
+                    style: S.button,
+                    disabled: busy === 'reach',
+                    onClick: checkReachability,
+                  }, 'Check reachability'),
+                  reachability
+                    ? h('span', { style: { ...S.meta, flex: 1 } },
+                      reachability.ok
+                        ? `Reachable at ${reachability.url}${reachability.upnp?.mapped ? ' (UPnP mapping)' : ''}`
+                        : `Not reachable${reachability.upnp?.available === false ? ' — no UPnP gateway on this network' : reachability.hint ? ` — ${reachability.hint}` : ''}`)
+                    : null,
+                ),
               )
               : h('div', null,
                 h('div', { style: { display: 'flex', gap: '8px', flexWrap: 'wrap', alignItems: 'center' } },
@@ -580,6 +702,13 @@ window.__ModuleLoader__.load({
             h('div', { style: { marginBottom: '8px' } },
               h('strong', null, request.deviceName),
               ` wants to control this computer (account ${shortAccount(request.userId)}).`),
+            h('div', { style: { ...S.meta, marginBottom: '8px' } },
+              [
+                request.sas ? `SAS ${request.sas}` : '',
+                request.fingerprint ? `key ${String(request.fingerprint).slice(0, 12)}` : '',
+                request.relay ? `via ${request.relay}` : '',
+                request.relayChanged ? 'relay changed since the last approval' : '',
+              ].filter(Boolean).join(' · ')),
             h('div', { style: { display: 'flex', gap: '8px' } },
               h('button', {
                 type: 'button', style: { ...S.button, ...S.primary }, disabled: busy === request.requestId,
@@ -613,6 +742,32 @@ window.__ModuleLoader__.load({
                   ),
                   peer.approved
                     ? h('span', { style: { ...S.chip, ...S.chipOk } }, 'Trusted')
+                    : null,
+                  peer.approved
+                    ? h('span', {
+                      style: { ...S.chip, ...(peer.forwardSecrecy ? S.chipOk : S.chipWarn) },
+                      title: peer.forwardSecrecy ? 'Ephemeral channel established' : 'Only static agreement (restart or re-approve to refresh)',
+                    }, peer.forwardSecrecy ? 'E2E' : 'static')
+                    : null,
+                  peer.approved && peer.fingerprint
+                    ? h('span', { style: S.meta, title: `fingerprint ${peer.fingerprint}` }, String(peer.fingerprint).slice(0, 8))
+                    : null,
+                  peer.approved && Array.isArray(peer.scopes)
+                    ? h('span', { style: S.meta, title: peer.scopes.join(', ') }, `${peer.scopes.length} scopes`)
+                    : null,
+                  peer.approved && peer.needsReapproval
+                    ? h('span', {
+                      style: { ...S.chip, ...S.chipBad },
+                      title: 'This approval has no agreement key; approve again to enable encryption',
+                    }, 'Re-approve')
+                    : null,
+                  peer.approved
+                    ? h('button', {
+                      type: 'button',
+                      style: S.button,
+                      disabled: busy === peer.deviceId,
+                      onClick: (event) => { event.stopPropagation(); revoke(peer.deviceId) },
+                    }, 'Revoke')
                     : peer.connecting
                       ? h('span', { style: { ...S.chip, ...S.chipWarn } }, 'Waiting')
                       : h('button', {
@@ -663,6 +818,8 @@ window.__ModuleLoader__.load({
 
     return {
       inject: ['slots'],
+      // Exposed for the headless render test (scripts/client-render-test.mjs).
+      __components: { Icon, DevicesPage, Chat },
       apply(ctx) {
         ctx.slots.inject('sidebar.panellist', () => ctx.slots.register({
           name: 'sidebar.panellist', id: 'devices', order: 20, label: () => 'Devices',

package/host/crypto.js

@@ -0,0 +1,145 @@
+import { createCipheriv, createDecipheriv, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes } from 'node:crypto'
+
+/**
+ * Random-nonce AEAD for unreliable transports: a duplicated or reordered
+ * datagram is harmless because each packet carries its own nonce, and plaintext
+ * replay is stopped at the request layer by the signed timestamp + nonce.
+ */
+export function createBoxCipher(key) {
+  const TAG = 16
+  return {
+    seal(plaintext) {
+      const nonce = randomBytes(12)
+      const cipher = createCipheriv('chacha20-poly1305', key, nonce, { authTagLength: TAG })
+      const body = Buffer.concat([cipher.update(Buffer.from(plaintext)), cipher.final()])
+      return Buffer.concat([nonce, body, cipher.getAuthTag()]).toString('base64')
+    },
+    open(packet) {
+      const raw = Buffer.from(String(packet), 'base64')
+      if (raw.length < 12 + TAG) throw new Error('box: short packet')
+      const nonce = raw.subarray(0, 12)
+      const tag = raw.subarray(raw.length - TAG)
+      const body = raw.subarray(12, raw.length - TAG)
+      const decipher = createDecipheriv('chacha20-poly1305', key, nonce, { authTagLength: TAG })
+      decipher.setAuthTag(tag)
+      return Buffer.concat([decipher.update(body), decipher.final()])
+    },
+  }
+}
+
+/**
+ * Peer channel crypto (phase A2).
+ *
+ * Static-static X25519 agreement per device pair, HKDF-SHA256 to a 32-byte
+ * session key, then ChaCha20-Poly1305 with a per-direction counter nonce:
+ *
+ *   nonce = 1 byte direction | 11 byte big-endian counter
+ *
+ * The receiver demands the exact next nonce, so a replayed, reordered or
+ * forked packet fails authentication instead of decrypting. AAD is empty
+ * because the nonce already binds direction and position; the ciphertext is
+ * authenticated over its full length.
+ *
+ * Known limitation: static keys give no forward secrecy. Replacing this with a
+ * Noise-IK-style ephemeral handshake is the next step; the wire format already
+ * carries a version tag so both can coexist.
+ */
+
+export const CHANNEL_VERSION = 1
+
+/**
+ * Ephemeral key agreement for forward secrecy.
+ *
+ * The session key mixes one ephemeral DH (fresh per pairing) with one static DH
+ * that authenticates the peer's long-term key. The ephemeral private key is
+ * dropped when the pairing context is disposed, so a later compromise of the
+ * long-term keys cannot reconstruct past session keys.
+ *
+ * This is IK-shaped but NOT a Noise implementation: no protocol name hash, no
+ * handshake transcript beyond the fingerprint salt. Do not describe it as Noise.
+ */
+export function generateEphemeralKeypair() {
+  return generateKeyPairSync('x25519')
+}
+
+export function ephemeralPublicPem(pair) {
+  return pair.publicKey.export({ type: 'spki', format: 'pem' })
+}
+
+export function deriveEphemeralKey({
+  ephemeralPrivate,
+  peerEphemeralPublicPem,
+  staticPrivate,
+  peerStaticPublicPem,
+  myFingerprint,
+  peerFingerprint,
+  label = 'channel',
+}) {
+  const ephemeralShared = diffieHellman({
+    privateKey: ephemeralPrivate,
+    publicKey: createPublicKey(peerEphemeralPublicPem),
+  })
+  const staticShared = diffieHellman({
+    privateKey: staticPrivate,
+    publicKey: createPublicKey(peerStaticPublicPem),
+  })
+  const salt = Buffer.from([myFingerprint, peerFingerprint].sort().join(':'), 'utf8')
+  const info = Buffer.from(`dsh-remote-control/${label}-fs/v${CHANNEL_VERSION}`, 'utf8')
+  return Buffer.from(hkdfSync('sha256', Buffer.concat([ephemeralShared, staticShared]), salt, info, 32))
+}
+
+export function deriveSessionKey({ privateKey, peerPublicKeyPem, myFingerprint, peerFingerprint, label = 'channel' }) {
+  const peerPublicKey = createPublicKey(peerPublicKeyPem)
+  const shared = diffieHellman({ privateKey, publicKey: peerPublicKey })
+  const salt = Buffer.from([myFingerprint, peerFingerprint].sort().join(':'), 'utf8')
+  const info = Buffer.from(`dsh-remote-control/${label}/v${CHANNEL_VERSION}`, 'utf8')
+  return Buffer.from(hkdfSync('sha256', shared, salt, info, 32))
+}
+
+function nonceFor(direction, counter) {
+  const nonce = Buffer.alloc(12)
+  nonce[0] = direction
+  nonce.writeBigUInt64BE(BigInt(counter), 4)
+  return nonce
+}
+
+/**
+ * One direction-aware AEAD pair for a peer session. `side` fixes which
+ * direction byte this endpoint sends with, so both peers agree without
+ * negotiating it on the wire.
+ */
+export function createCipherPair(key, side) {
+  const sendDirection = side === 'a' ? 1 : 2
+  const receiveDirection = side === 'a' ? 2 : 1
+  let sendCounter = 0
+  let lastReceived = -1n
+
+  return {
+    seal(plaintext) {
+      const nonce = nonceFor(sendDirection, sendCounter)
+      const cipher = createCipheriv('chacha20-poly1305', key, nonce, { authTagLength: 16 })
+      const body = Buffer.concat([cipher.update(Buffer.from(plaintext)), cipher.final()])
+      sendCounter += 1
+      return Buffer.concat([nonce, cipher.getAuthTag(), body]).toString('base64')
+    },
+    open(packet) {
+      const raw = Buffer.from(String(packet), 'base64')
+      if (raw.length < 28) throw new Error('channel: short packet')
+      const nonce = raw.subarray(0, 12)
+      if (nonce[0] !== receiveDirection) throw new Error('channel: wrong direction')
+      const counter = nonce.readBigUInt64BE(4)
+      // Monotonic acceptance: a replayed or older packet is refused, while a
+      // gap left by a dropped message does not wedge the channel forever.
+      if (counter <= lastReceived) throw new Error('channel: replay')
+      const tag = raw.subarray(12, 28)
+      const body = raw.subarray(28)
+      const decipher = createDecipheriv('chacha20-poly1305', key, nonce, { authTagLength: 16 })
+      decipher.setAuthTag(tag)
+      const plain = Buffer.concat([decipher.update(body), decipher.final()])
+      lastReceived = counter
+      return plain
+    },
+    stats: () => ({ sent: sendCounter, received: lastReceived >= 0n ? Number(lastReceived) + 1 : 0 }),
+    reset() { sendCounter = 0; lastReceived = -1n },
+  }
+}