# moonrelay spec —— 结构事实与契约

版本:**v0.1**(2026-10-28 立卷,骨架期)
定位:DERP 形包级加密中继的**结构事实与契约**卷。纪律底卷 =
[const.md](const.md)(必须/禁止句式);本卷记协议事实、形状与验收门。

## 一、范围

### 做

- **帧面**:自研消息集词表(REGISTER/FORWARD/KEEPALIVE/HEALTH/
  EVACUATE/ACCEPT/REJECT 七型)+ 线型 [version 1B][type 1B]
  [length u16be] 载荷;协商不上断连不猜,未知型拒(封闭系统不识即
  版本错位),逐型长度门,旧字节含义永不变。`[已落]`
- **准入缺省形态定谳(T1)**:**缺省拒**——server 面准入策略为显式
  数据参数(RejectAll 起手;AcceptAll 显式才开;宪法律 1.3「禁止
  缺省无门开放」);token 形准入槽 trait 候 T3。`[定谳]`
- **加密面**:包级加密 per-recipient(密钥不落中继;HKDF-SHA256
  salt=recipient_id 派生 + AES-GCM seq-nonce + 64 槽滑窗防重放),
  算法层单一真源 mooncry,本仓零自带密码学;认证失败统一拒因
  ("record auth failed",不漏 oracle)。`[已落]`
- **泵纯核**:限速器(令牌桶一形三档:单端/全局/惩罚,速率参数可配)
  + 配对窗(首到挂窗次到即配即摘,单线程 reducer 无竞态)+ 降级判定
  (累计跨窗均值超阈粘性降,冷启动豁免)+ 疏散编排(停新收留→广播
  迁端点→存量排空)+ 每端缓冲上界(背压出调度者)——全纯函数 +
  `now : Int64` 注入,sim 回放。`[已落]`
- **准入槽**:trait 沉没门;缺省形态已定谳 = 缺省拒(数据参数)。
  资源边界 = 限速 + 每端缓冲深度,全参数可配。`[已落]`
- **服务端 IO 面**:server/ 包(lib 面:RelayServer 装配 + FrameReader
  流分帧 + PeerRegistry 端点册 + 六幕处理环)+ cmd/ 入口(lib/cmd
  分立)+ 注册纳/FORWARD 限速三层直递/KEEPALIVE/疏散广播/停新拒。
  `[已落]`

### 暂不做

- 与 RustDesk relay / iroh DERP 的线级兼容(思想借,线自研)。
- 多租户计费 / 集群拓扑 / Web 控制台。
- TURN(RFC 5766)兼容——中继协议全自研。
- 默认域名/端点名单(剥离纪律,配置注入)。

## 二、形状锚

- **只见密文**:转发面载荷 opaque 透传 + per-recipient 包级加密;
  中继软件作者即潜在攻击者(assume a malicious relay)。
- **纯核/IO 分界**:泵决策面纯函数(`now : Int64` 注入),IO 面
  async 薄壳;库面与部署面分包(executable 不可被 import)。
- **错误面**:`RelayError = pub(all) suberror`(Malformed /
  PolicyRejected / RelayFailure),政策错与协议错分面。

## 三、验收门

| 面 | 门 |
|---|---|
| 帧面 | 自作词表已知答案罐 + version 协商拒罐 |
| 加密面 | mooncry 向量对拍 + 破密文拒罐(认证 oracle 防线) |
| 泵纯核 | 限速/配对/降级/疏散 sim 回放罐 |
| 真网络 | 真机黄金门(候部署环境,挂账) |

## 四、血统

iroh DERP 形与优雅疏散思想 / RustDesk relay 资源面结构思想(限速
三层、降级窗)——思想与结构参考,实现与线全自研(clean-room,
Apache-2.0)。