READMESource: main@f9092092
@dsh-remote/protocol
DSH Remote Control 的线协议层:密封记录(XSalsa20-Poly1305)、方向密钥派生(KDF)、
中继控制帧与构造器、cmd.* / ev.* 载荷目录、错误码可重试表、协议版本闸、防休眠命令构造器。
纯函数、零 I/O:不认识时钟、不认识平台、不发定时器——所以每条冻结契约都能脱离环境 逐字节被测(含 golden vectors 对拍:与小程序里那份保留实现的 SHA-256 锚定)。
安装
npm install @dsh-remote/protocol
结构
| 子路径 | 内容 |
|---|---|
…/keys |
PSK 生成、两把方向密钥的 HKDF 风格派生、计数器 nonce |
…/record |
seal() / open()——基于 tweetnacl 的密封记录 |
…/frames |
中继控制帧的 zod schema + 解析器(帧名冻结) |
…/outbound |
同一批帧的构造器(产物保证过 schema) |
…/payloads |
cmd.* / ev.* 载荷目录的 zod schema |
…/limits |
三端共享的数值预算(帧上限 / 附件上限 / 去重窗口) |
…/registry |
帧名 / 载荷名 / 能力 id 的注册表(编译期与 zod 联合一致) |
…/classify |
帧的分类(谁向谁、能不能重试) |
…/errors |
错误码表与可重试判定 |
…/idempotency |
请求幂等去重窗口 |
…/negotiate |
协议版本闸(单版本严格校验)+ PROTOCOL_VERSION |
…/report-version |
DRC_REPORT_VERSION 判定(版本上报开关,仅小程序上传在用) |
…/pairing |
6 位配对码工具(randomPairingToken / formatPairingToken) |
…/ids |
会话 / 主机 / 命令 id 的生成与前缀 |
…/sleep |
防休眠命令构造器(caffeinate / systemd-inhibit) |
完整清单见 package.json 的 exports;根入口会把全部子路径再导出一次。
红线
- 协议中立:不引入任何传输层(WS / SSE / HTTP)与平台概念——游标、ack 这类 会话层语义可以进协议,但「因为是 WS 所以……」不可以。
- 帧名与载荷名冻结:改动既有形状就是破坏性变更,必须升
PROTOCOL_VERSION并让三端一起升(hello.protocol必填且必须与本端相等,不相等的一端在握手上就被拒)。 加性演进不升号(新增可选字段 / 新帧名),新行为走能力协商: 中继在hello-ok.capabilities里声明、端点按声明开(发版含义见伞仓docs/RELEASE.md)。 - 本包不许出现
node:fs/node:os/process.*(I/O 全部在消费方)。
开发
pnpm install
pnpm test # tsc 构建 + node --test
pnpm typecheck
许可
MIT
No comments yet. Be the first to write one.