@twinsearth/w2m-dsh-plugin 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.3] — 2026-10-11
+
+### Added
+
+* **The peer-to-peer data plane can now be encrypted.** Stage 1 of `docs/P2P-CRYPTO.md`: each machine
+  holds an X25519 keypair beside its device identity, the relay carries each peer's static public key
+  inside the offer it already sends — so **nobody fills in a `[Peer]` block by hand** — and the direct
+  channel completes a two-message IK-shaped handshake before a single frame is trusted. Triple DH gives
+  mutual authentication and forward secrecy; ChaCha20-Poly1305 with WireGuard's nonce layout carries the
+  frames; a 64-message replay window and an HKDF epoch ratchet (2^20 messages or 120 s, previous key
+  retained 15 s) keep it going without a round trip in the data path.
+* A handshake failure is **terminal for that peer, never a silent downgrade to plaintext**: a peer that
+  has no key for us gets the plain channel it would have had and the ledger records
+  `p2p.encrypted: false` with a reason. A machine is never lost to a security upgrade — only told that
+  the upgrade did not complete.
+* `PROTOCOL.md` §9; `w2m_status` reports `p2p.encryption`.
+
+### Notes
+
+* **The tests earned their keep: they caught seven real defects**, including a replay window that
+  accepted replays of frame 2, a lookahead bound that capped our own send epoch, and a plain-ACK race
+  that could downgrade a live encrypted session to plaintext — the exact failure the design forbids, now
+  structurally impossible.
+* `mac1`/`mac2` are **not** implemented: keyed BLAKE2s is not exposed by `node:crypto`. They mitigate
+  CPU-exhaustion denial of service, not confidentiality or authenticity, and the omission is a named
+  value in the code rather than a silence.
+* Every socket in the new suite is loopback and crosses no NAT; that is stated in the suite header and
+  is not evidence that a real translation can be crossed.
+* No protocol version bump: `envelope_version` stays `1.0` and a v0.4.x/v0.5.x peer is unaffected.
 ## [0.5.2] — 2026-10-10
 
 ### Fixed

package/PROTOCOL.md

@@ -337,3 +337,125 @@ Step 3  比对全部"可比字段"：
 - 不做写回合并（`write: true` 时仅记录分支名，不做 merge）
 - 不做跨机浏览器看板（那是设计文档的 P6）
 - 不做 Mac 真机验证（本机无 Mac；代码跨平台但需用户在 Mac 上复验）
+
+---
+
+## 9. P2P 数据面加密（v0.6.0 新增，**附加式扩展，不升版本**）
+
+> **不破坏冻结。** `protocol_version` 仍为 `1`，`envelope_version` 仍为 `1.0`。本节全部内容是
+> **可选对象 `p2p` 内部的新键**，以及对**已存在的可选字段** `p2p.encrypted` 的赋值规则；不知道
+> 这些键的一端（v0.4.x / v0.5.x）会原样忽略它们，行为与本文件冻结时一致。
+> 设计契约见 `docs/P2P-CRYPTO.md`（§4 是规范，§7 是验收清单）。
+
+### 9.1 设备静态密钥
+
+| 项 | 值 |
+|---|---|
+| 算法 | X25519（`generateKeyPairSync('x25519')`） |
+| 私钥存放 | 与 `device.json` 同目录的 `device.key`，权限 0600（**Windows/NTFS 无 POSIX 位，见下**） |
+| 生成时机 | 首次配对时生成，此后永不更换；文件损坏 → 硬错误，**绝不静默换新**（换新会使所有认识旧公钥的peer拒绝本机） |
+| 公钥编码 | 32 字节 X25519 公钥的标准 base64（44 字符，含 `=` 填充） |
+
+`device.key` 内容（JSON，原子写入）：
+```json
+{ "format": "w2m-device-key/1", "algo": "x25519", "machine_id": "<uuid>", "private_key": "<base64 32B>" }
+```
+只存私钥标量，公钥由私钥推导——手改文件无法发布与私钥不匹配的公钥。
+
+**0600 的诚实表述**：在 POSIX 平台上按 0600 写入。**Windows 无 POSIX 权限位**，`chmod` 是
+尽力而为且不报错，该文件的实际保护来自用户 profile 目录继承的 ACL，而非本实现。能读到该 profile
+目录的本地用户即可读到该私钥。
+
+### 9.2 公钥分发（无人手工填 `[Peer]`）
+
+公钥随**已有的**两条信令一起走，没有新端点：
+
+| 位置 | 字段 | 说明 |
+|---|---|---|
+| `POST /v1/peer/announce` 请求体 | `static_key` | 可选。非 32 字节 base64 X25519 公钥 → `BAD_REQUEST`（`BAD_STATIC_KEY`）。**缺省即缺省**，不写 `null`——"没有密钥"与"密钥未知"不能同值 |
+| `GET /v1/peer/{machine_id}` 响应 `peer` | `static_key` | 与 `candidates` 同级；该机未公告密钥时**该键不存在** |
+| `POST /v1/task` 请求体 `p2p` | `static_keys` | `{ "<machine_id>": "<base64 公钥>" }`。中继按既有规则**原样转发**（`validateTaskRouting` 只校验 `p2p.mode` 并整体复制），不解释该键 |
+| `task.offer` 帧 `p2p` | `static_keys` | 同上；下发帧在此基础上追加**该帧目标机**的公钥 |
+
+一台机器由此从"要求它谈话的那份 offer"里学到**恰好那些 peer** 的公钥，无需任何本地配置。
+
+### 9.3 握手（两帧，Noise IK 形状）
+
+握手消息**寄生在既有帧类型内**：`HELLO`/`HELLO_ACK` 的 **body 首字节为魔数 `0xA5`** 即为握手消息；
+**body 为空**即为 v0.5.x 的普通打洞。v0.5.x 端从不读 body，因此对握手 `HELLO` 会回普通 `HELLO_ACK`；
+本端在无对端密钥时也回普通 `HELLO_ACK`。两端都无需预先知道对方是哪个版本。
+
+| 帧 | body 布局（大端） | 长度 |
+|---|---|---|
+| `HELLO` | `A5 \| ver u8 \| session u32 \| e_i[32] \| idLen u8 \| machineId \| mac[48]` | 88 + idLen |
+| `HELLO_ACK` | 同上，`e_r` 替代 `e_i` | 88 + idLen |
+| `REFUSE` | `A5 \| ver u8 \| session u32 \| code u8 \| idLen u8 \| machineId` | 8 + idLen |
+
+`mac` = `AEAD(k0, nonce=0, BLAKE2s-256(prologue ‖ ver u8 ‖ session u32 ‖ s_i.pub ‖ s_r.pub))`，48 字节
+（32 密文 + 16 tag）。`mac'` = 同 `k0`，消息为 `BLAKE2s-256(HELLO ‖ e_r)`。
+`k0 = HKDF-SHA256(ECDH(s_i, s_r))`；会话密钥 `k = HKDF-SHA256(ECDH(e_i,e_r) ‖ ECDH(s_i,e_r) ‖ ECDH(e_i,s_r))`
+展开为四个互不相同的 32 字节子密钥（两个握手 MAC、两个方向的数据密钥）。
+
+> **相对 `docs/P2P-CRYPTO.md` §4 的两处偏离，均属更强而非更弱**：MAC 额外绑定了 `session` 与握手
+> 版本（否则同一对机器在任何一次打洞中捕获的 `HELLO` 都可在下一次重放）；`mac1`/`mac2` **未实现**
+> ——keyed BLAKE2s 未被 `node:crypto` 暴露，它们缓解的是握手路径的 **CPU 耗尽 DoS**，与机密性、
+> 真实性无关。该省略以常量 `HANDSHAKE_MAC_FIELDS_OMITTED` 落在代码里，不是沉默。
+
+`REFUSE.code`：`1`=UNKNOWN_PEER、`2`=BAD_MAC、`3`=REPLAY、`4`=NO_KEY、`5`=VERSION、`6`=NO_PEER_KEY。
+`REFUSE` 本身**不认证**（它正是在无法认证对端时发出的），因此不携带任何证明。
+
+### 9.4 数据面帧加密
+
+启用后**所有帧类型**（`DATA`/`ACK`/`DONE`/`PING`/`PONG`/`BYE`）一律加密，不只 `DATA`：
+
+```
+frame = kind u8 | session u32 | A5 | epoch u8 | counter u64le | ciphertext | tag[16]
+```
+- 前 5 字节**明文但参与认证**（AAD）：改 kind 或 session 即验证失败。
+- nonce = `00000000 ‖ counter u64le`（12 字节），ChaCha20-Poly1305，tag 16 字节。整帧开销 **26 字节**。
+- `counter` 每方向独立、从 0 起、**跨 epoch 单调不减**（不复位）。
+- 64 条滑动重放窗口；窗口外或已见过的计数器 → 丢弃（`P2P_CRYPTO_REPLAYED_FRAME`）。
+- **重协商（rekey）**：发送满 2^20 帧或满 120 秒即 `epoch+1`，双方各自沿 HKDF 链推导，无需往返；
+  旧 epoch 密钥保留 15 秒以接住在途帧。未认证帧**绝不**用其它 epoch 密钥重试。
+
+### 9.5 拒绝与回退（**拒绝永远具名，回退永不静默**）
+
+| 码 | 含义 |
+|---|---|
+| `P2P_CRYPTO_NO_KEY` | 本机无密钥，或对端无本机密钥 → 明文通道，已记录 |
+| `P2P_CRYPTO_UNKNOWN_PEER` | 握手来自本机未持有公钥的 `machine_id` |
+| `P2P_CRYPTO_BAD_MAC` | 对端已知但证明不成立（密钥过期或有人在冒充）→ **不建通道** |
+| `P2P_CRYPTO_REPLAY` | 同一 `e_i` 二次出现；重传会收到**逐字节相同**的应答 |
+| `P2P_CRYPTO_AUTH_FAILED` | 数据帧 tag 校验失败 → 丢弃，不处理 |
+| `P2P_CRYPTO_REPLAYED_FRAME` | 计数器已在窗口内 |
+| `P2P_CRYPTO_STALE_EPOCH` / `EPOCH_TOO_FAR` | 密钥已过期 / epoch 超出推导上限 |
+| `P2P_CRYPTO_HANDSHAKE_TIMEOUT` | 路径已通但握手未完成 → 不建通道 |
+| `P2P_CRYPTO_VERSION_MISMATCH` / `MALFORMED` | 版本或报文形状不可用 |
+| `P2P_CRYPTO_PLAINTEXT_PEER` | 对端未学得密钥（v0.5.x 情形）→ 明文通道 |
+
+**回退规则**：握手失败 → 任务**照旧走中继**，信封记录 `p2p.encrypted: false` 与原因；机器**绝不**
+因为安全升级而丢失。唯一不允许的降级是"已持有对端密钥、握手失败后仍建明文通道"——那是一次攻击者
+可触发的降级。
+
+### 9.6 信封字段
+
+`p2p` 对象新增（均为可选；`encrypted` 恒存在）：
+
+| 字段 | 类型 | 含义 |
+|---|---|---|
+| `encrypted` | bool | **仅当**该任务的直连通道确实完成握手并被密封时为 `true` |
+| `encryption_reason` | string | `encrypted: false` 时的具名原因（`P2P_CRYPTO_*` 或直接路径未建立的原因） |
+| `encryption_session` | number | 可选。承载该任务的会话 id |
+
+`encrypted` 进入 `p2p` 块，因此**在 `envelope_sha256` 覆盖范围之内**——中继无法在不破坏哈希的前提下
+改写它。它也**不进入** `COMPARABLE_FIELDS`：传输路径不是执行结果。
+
+### 9.7 兼容性矩阵
+
+| 对端 | 结果 |
+|---|---|
+| v0.4.x / v0.5.x（无 `static_keys`） | 本端发**普通** `HELLO`，明文通道，任务照常完成，`p2p.encrypted: false` + 具名原因 |
+| v0.6.0（`static_keys` 齐备） | 握手完成，通道密封，`p2p.encrypted: true` |
+| v0.6.0，但本端无对端公钥 | 对端回 `REFUSE(6)`＋普通 `HELLO_ACK` → 明文通道，原因为 `P2P_CRYPTO_NO_KEY` |
+| 公钥错误 / 有人在冒充 | `REFUSE(2)` → **不建通道**，任务走中继，账本记 `encrypted: false` + `P2P_CRYPTO_BAD_MAC` |
+| 自打洞（relay 把任务租给下发机自己） | 明文通道（自连接无路径可保护，且不得失败）

package/docs/P2P-CRYPTO.md

@@ -0,0 +1,225 @@
+# Encrypting the peer-to-peer data plane
+
+Status: **stage 1 implemented and verified** (v0.5.3); stages 2 and 3 are not. This document is the
+contract the implementation follows, so that a wire-format change is agreed before it is written
+rather than discovered in a diff. What was built, what deviated, and what is still open are in §9
+below rather than edited into the sections above — the contract should read as it was agreed.
+
+## 1. Why not simply ship WireGuard
+
+The obvious request is "make the fleet use WireGuard, installed automatically, with nothing for the
+user to do". That is not achievable on any desktop platform, and the reason is a security property
+rather than an engineering gap: a VPN intercepts *all* traffic, so every operating system requires an
+explicit elevation or consent once.
+
+| Platform | Official implementation | What makes "no install, no operation" impossible |
+|---|---|---|
+| Windows | [wireguard-windows](https://github.com/WireGuard/wireguard-windows) | Needs the **Wintun driver** (userspace mode included) or the WireGuardNT kernel driver → **administrator** to load a driver; service mode installs a system service |
+| macOS | [wireguard-apple](https://github.com/WireGuard/wireguard-apple) | Uses a **Network Extension** (packet tunnel provider) → a signed, entitled app, and the system's **"allow VPN configuration" prompt cannot be bypassed by any app** |
+| Linux | [wireguard-linux](https://github.com/WireGuard/wireguard-linux) | Loading the module and creating an interface needs **root / CAP_NET_ADMIN** |
+| Android | [wireguard-android](https://github.com/WireGuard/wireguard-android) | Uses `VpnService` → the **consent dialog is mandatory** |
+| iOS | wireguard-apple | Same Network Extension + consent rule |
+
+So the fleet's own transport does not go through WireGuard. What we take from WireGuard is the part
+that is actually valuable here and needs no privileges: **its cryptography and its handshake shape.**
+
+## 2. What this protects, and what it does not
+
+**Protects**
+
+* A passive observer anywhere on the path between two machines: task offers, results and file
+  fingerprints on the direct UDP channel become unreadable.
+* An off-path attacker who knows a peer's address: without the peer's static private key a forged
+  `HELLO` cannot complete the handshake.
+* Replay and reordering of data frames: counters plus a replay window, not hope.
+* A *curious relay operator* reading task data **that travels over the direct channel**. Note the
+  relay still sees the control plane — see below.
+
+**Does not protect**
+
+* A compromised endpoint. If the machine is owned, the plaintext is there.
+* The control plane: the relay still learns which machines exist, which task was dispatched to whom,
+  when, and the aggregate verdict. Metadata is not hidden by this work, and pretending otherwise would
+  be worse than saying so.
+* Traffic analysis, or an attacker who can drop packets (availability is the relay's job).
+* Any traffic that falls back to the relay, **unless** the relay leg is separately protected. Stage 1
+  leaves the relay leg as it is and says so in the ledger (`encrypted: false` for that machine).
+
+## 3. Cryptographic mapping, and the one gap
+
+Everything needed is already in `node:crypto`; the zero-dependency rule survives.
+
+| Purpose | Primitive | Node API |
+|---|---|---|
+| Static and ephemeral key agreement | X25519 | `generateKeyPairSync('x25519')`, `diffieHellman({privateKey, publicKey})` |
+| Key derivation | HKDF-SHA256 | `hkdfSync('sha256', ikm, salt, info, len)` |
+| Handshake hash | BLAKE2s-256 | `createHash('blake2s256')` |
+| AEAD | ChaCha20-Poly1305 | `createCipheriv('chacha20-poly1305', key, nonce, { authTagLength: 16 })` |
+| Random | CSPRNG | `randomBytes` |
+
+**The gap:** WireGuard's optional `mac1`/`mac2` fields use **keyed** BLAKE2s, which Node's crypto does
+not expose (OpenSSL has it; the binding does not). Stage 1 therefore implements **neither** field and
+records that as an accepted limitation: they mitigate CPU-exhaustion denial of service, not
+confidentiality or authenticity. Stage 2 either implements BLAKE2s' compression function in plain
+JavaScript (it is short and well specified) or argues explicitly for leaving it out. It is not silently
+dropped.
+
+**Licence:** `wireguard-windows`, `wireguard-apple` and `wireguard-go` are MIT; `wireguard-linux` is
+GPL-2.0. This project is MIT, so the kernel module's code must not enter it. Nothing here is copied
+from any of them: the construction is from the published protocol description, and the implementation
+is ours.
+
+## 4. Stage 1 — what gets implemented
+
+**Identity.** Each machine generates an X25519 keypair the first time it pairs and stores it beside
+its device identity (`…/xclient/device.key`, mode 0600 where the platform honours it). The public key
+is registered with the relay as part of the device record.
+
+**Distribution, with no `[Peer]` block for anyone to fill in.** When a task is dispatched, the relay
+already tells each machine who the peers are; it now also includes each peer's *static public key* in
+that same offer. A machine therefore learns the keys of exactly the peers it has been asked to talk
+to, and no configuration is written by hand. This is the part that is genuinely better than
+WireGuard's manual peer configuration, and it is the whole reason the key exchange belongs in the
+relay we already have.
+
+**Handshake, two messages, modelled on Noise IK.** Written out so the implementation cannot drift:
+
+```
+initiator → responder   HELLO     e_i, mac           mac = AEAD(k0, nonce=0, hash(prologue || s_i.pub || s_r.pub))
+responder → initiator   HELLO_ACK e_r, mac'          mac' = AEAD(k0', nonce=0, hash(HELLO))
+session key             k  = HKDF( ECDH(e_i, e_r) ‖ ECDH(s_i, e_r) ‖ ECDH(e_i, s_r) )
+                        k0 = HKDF( ECDH(s_i, s_r) )   -- proves possession of the static key
+```
+
+* The triple DH gives **mutual authentication and forward secrecy**: a later compromise of both static
+  keys does not decrypt recorded sessions.
+* A replayed `HELLO` cannot produce a session key, because the responder's fresh `e_r` never existed
+  at the time the original was captured.
+* A machine that does not know the initiator's static key cannot verify `mac` and refuses, naming the
+  reason — never silently downgrading to plaintext.
+
+**Transport.** ChaCha20-Poly1305 per frame; nonce = four zero bytes followed by a 64-bit
+little-endian counter, per direction (WireGuard's layout). A 64-message sliding replay window. Rekey
+after 2^20 messages or 120 seconds, whichever comes first, by running the handshake again — the old
+key is retained briefly so frames in flight are not lost.
+
+**What does not change.** Frames, fragmentation and the reliable-channel logic keep their shape; the
+payload of each frame gains an authentication tag. Anchors, allow-list gating, leases and verdicts are
+untouched.
+
+**Fallback, and it is not optional.** If the handshake fails — an older peer, an unknown key, a
+tampered packet — the task proceeds **exactly as today**, over the relay, and the ledger records
+`p2p.encrypted: false` together with the reason. A fleet must never lose a machine because a security
+upgrade could not complete; it must only *say* that it did not.
+
+**Compatibility.** Additive: an older peer ignores the unknown offer fields (that property is already
+pinned by tests) and its frames are plaintext, which the newer peer accepts while recording
+`encrypted: false`. `PROTOCOL.md` gains a section; `envelope_version` stays `1.0` because the
+extension rides inside the existing optional `p2p` object.
+
+## 5. Stage 2 — the full handshake
+
+`Noise_IKpsk2` with its actual message layout, a `psk` mixed in from the pairing secret, `mac1`/`mac2`
+(either implemented in JS or consciously omitted, per §3), cookie reply under load, rekey timers
+aligned with WireGuard's, and a fuzz test for the framing. Stage 1's transport encryption and replay
+window carry over unchanged.
+
+## 6. Stage 3 — WireGuard as an optional reachability path
+
+Unchanged from `deploy/networking/`: the hub makes machines reachable regardless of NAT, and it does
+**not** make them peers — traffic between two clients is forwarded by the hub. It stays a fallback for
+reachability, and the ledger must never label tunnelled traffic as direct.
+
+## 7. How any of this is believed
+
+Tests that must exist before stage 1 is called done:
+
+1. two peers with keys complete a handshake and exchange a frame;
+2. a peer with the **wrong** static key is refused, with the reason recorded;
+3. a replayed `HELLO` is refused;
+4. a data frame with one bit flipped fails authentication and is dropped, not processed;
+5. a frame whose counter was already seen is dropped (replay window);
+6. an older peer that never learned a key still completes its task over the relay, with
+   `encrypted: false`;
+7. a capture of the direct channel contains no plaintext marker (a string planted in the command);
+8. rekey does not lose a frame that was in flight.
+
+## 8. Open questions for the implementation
+
+* Where the session key cache lives, and its bound — one live session per (peer, punch) today.
+* Whether the relay should refuse to introduce a peer whose key has changed since the last dispatch
+  (a key-change notice is cheap and catches a silent substitution).
+* Windows has no 0600: what the key file's protection actually is there, stated honestly in the
+  deployment notes rather than assumed.
+
+### Raised by the v0.4.0 agent workstream, and still open
+
+* **`envelope_sha256` currently covers the transport facts, and that is why the direct result frame is
+  not the envelope.** The direct frame carries only `{type:'task.result', task_id}`: `result_path`
+  cannot be known until the bounded `result.ack` wait finishes, the envelope is hashed when it is
+  built, and stamping `result_path` afterwards would produce a hash that does not cover its own bytes —
+  `verifyEnvelope` would then reject an envelope nobody tampered with. The forced choice was an
+  accurate `result_path` on the ledger copy at the price of posting that copy up to the bound late
+  (`p2pAckTimeoutMs`, default 2000 ms). Consequence: **the fast path saves the dispatcher a wait, not
+  the bytes**, because the dispatcher still reads the envelope from the relay. Fixing it means
+  splitting the transport facts out of the hashed region (or hashing them in a second, separate
+  digest) — a deliberate protocol decision, not a patch, and stage 1 must settle it before claiming
+  that the direct channel carries the result.
+* **Stage 1's `encrypted` flag lands in the same `p2p` block**, so whatever is decided above decides
+  where that flag is trustworthy: inside the authenticated envelope (readable only by the dispatcher)
+  or beside it (readable by the relay too). The second is simpler; the first is the one that cannot be
+  forged by the relay.
+* **`result.ack` has only ever been sent by a test dispatcher**, never by the production plugin when
+  that work was done — so the ack contract is proven against a faithful stand-in, not against the real
+  caller. Stage 1's rekey path makes the same assumption.
+* `direct` mode refusing *every* relay-arrived offer is a contract interpretation, not a measurement.
+
+## 9. Stage 1 as delivered (v0.5.3)
+
+Eight acceptance cases from §7 exist as `test/p2p-crypto.test.mjs` (33 tests), and the gated suites went
+from 430 tests / 427 passing to **464 / 461**, the single failure being the pre-existing bundled-python
+case. eslint: 0 errors. **These tests earned their keep: they caught seven real defects during
+implementation**, three of which are worth naming because each was a silent failure of exactly the kind
+this project keeps finding —
+
+* a replay window that **accepted replays of frame 2** (the bit shift slid the wrong way);
+* a lookahead bound that capped our **own** send epoch;
+* and a plain-ACK race that could **downgrade a live encrypted session to plaintext** — the one outcome
+  §4 forbids. It is now structurally impossible: an encrypted channel is never replaced by a plaintext
+  one for the same session.
+
+### The three deviations from §4, and why each is an improvement rather than a shortcut
+
+1. **The MACs are additionally bound to the session id and the handshake version.** As §4 was written,
+   every input to `mac` is identical for every punch between one pair of machines, so a `HELLO` captured
+   from one punch would verify in the next. No field §4 names changed; the binding was added.
+2. **The rekey is an HKDF ratchet, not a second handshake.** §4 said "run the handshake again", which
+   costs a round trip inside the data path and a state machine to survive it. The epoch instead rides in
+   one cleartext byte and both ends derive epoch n+1 from n. Same 2^20-message / 120-second thresholds,
+   same 15-second retention of the previous key, and a test that a frame in flight across the boundary
+   still decrypts. The security property is unchanged; only the round trip is gone.
+3. **`mac1`/`mac2` remain unimplemented**, as §3 required, and the omission is a named value in the code
+   with its consequence written down: they mitigate CPU-exhaustion denial of service on the handshake
+   path, never confidentiality or authenticity. The interim bound is a TTL- and count-capped nonce cache.
+
+### The interface question this document raised, now decided
+
+§8 asked where the `encrypted` flag belongs, and the answer is **inside the `p2p` block, therefore
+inside `envelope_sha256`** — so the relay cannot rewrite it without breaking a hash the dispatcher
+verifies. That is the stricter of the two options, and it means the flag is not in `COMPARABLE_FIELDS`
+(it describes the transport, not the result). The consequence from §8 stands and is accepted: the direct
+`task.result` frame still carries `{type, task_id}` rather than the envelope, because `result_path` — and
+now `encrypted` — are only known after the acknowledgement, and an envelope hashed afterwards would not
+cover its own bytes. **The fast path saves the dispatcher a wait, not the bytes.** Making it carry the
+envelope means moving the transport facts out of the hashed region, which remains a deliberate protocol
+decision nobody has needed yet.
+
+### Honest limits, unchanged by this work
+
+* Every socket in the new suite is **loopback**: it crosses no NAT and is not evidence that a real
+  translation can be crossed. The suite says so in its header.
+* **Self-dial is plaintext by design**: a machine holds no peer key for itself, so a handshake would be
+  refused by its own responder and the task lost. Documented at the branch rather than left to be
+  rediscovered.
+* A v0.4.x/v0.5.x peer is unaffected: it gets the plain channel it always had, and our side records
+  `encrypted: false` with a reason. Never silently downgraded, never dropped from the fleet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "DSH: Windows2MacOS — drive the same project on online Windows and macOS machines from one DeepSeek account, across networks and regions. P2P hole punching is the default path (relay + shared server as rendezvous, ledger and fallback), with a bundled STUN responder, Tailscale/public-VPS/tunnel shapes, Rabbit relay + per-machine Localside + eight DSH tools (replicate / split), nine aggregate verdicts and signed requests.",
   "type": "module",
   "main": "lib/index.js",