Hermes/msa-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity
17 Commits 1 Branch 3 Tags
62b322af39273e867183343b66dd464a82e9106e
Commit Graph
10 Commits
Author SHA1 Message Date
chick 62b322af39 feat(agent,relay): 节点自注册与一键卸载 
节点侧现在有两条命令覆盖整个生命周期，中继侧有了一条让节点不必被人工登记就能加入
的通道。

agent 新增两个子命令：

- `msa-agent enroll --relay <url> [--code <code>]` 铸造密钥与标识并写配置。它和
  `msa-keygen` 共用 internal/enroll，所以两者不会对"配置长什么样"产生分歧——区别只在
  运行位置：keygen 需要 Go 工具链，而节点上只有交叉编译好的二进制。带 --code 时它自己
  向中继登记，顺序是先登记再落盘：为"中继还不认识的节点"写下的配置会永远重试 401，而
  运维无法把这种情况和网络故障区分开。
- `msa-agent uninstall [--dry-run] [--keep-logs]` 按唯一一个不会留下悬挂状态的顺序拆除：
  先清设备并告诉中继，再停服务、删单元、删配置目录、删日志、删用户。顺序是重点——先删
  节点会让中继继续向一台已经不存在的节点投递，而"一键卸载"此前根本不存在，尽管安装会
  往宿主机放六样东西，其中配置里还有节点密码。

  写这个时踩到一个值得记的坑：第一版把每个动作都写成"先 log 再执行"，于是 --dry-run
  会真的停掉服务——一个不是 dry run 的 dry run。现在每个副作用都 gate 在 step() 的
  返回值上，并有测试断言 dry run 一条命令都不跑。

中继新增自注册，默认关闭：

- `POST /v1/enroll/code`（运维令牌）铸造一次性码，15 分钟、最多 10 个未使用。
- `POST /v1/enroll` 节点用码登记自己。码先兑换再校验登记体，所以用垃圾请求探测码是否
  有效的尝试会烧掉它。
- 登记只授权"加入"这一件事。中继仍然读不到内容、伪造不了应答、下发不了命令——最坏情况
  是让一个不该出现的节点出现，也就是拒绝服务，正是设计已经接受的边界。
- agents.json 的条目优先于自注册状态，所以运维永远能用一个 diff 覆盖或吊销自注册的节点；
  反过来，节点不能覆盖运维条目（被拒绝，400）。
- 自注册状态要落盘，这是中继第一次有它必须记住的东西。中继此前无状态是它的一条性质，
  这里明确让掉了：忘记已登记的节点会让它们全部 401，而症状看起来像 token 坏了。状态文件
  原子写、损坏时拒绝启动（而不是静默变成空机群），systemd 单元用 StateDirectory 给它一块
  可写目录，其余文件系统仍是只读。

测试：internal/enroll 五项（两份产物必须描述同一个节点、密码只在给出时写入、给定标识
不被重新生成、两次铸造不同、缺输入被拒），internal/install 七项（删干净、顺序、中继不可
达仍完成、dry run 不动任何东西、保留日志、缺件不中止、计划列出每条路径），
test/enrollment.test.js 十四项（流程、码单次、垃圾请求烧码、默认关闭、只有运维能铸造、
不能覆盖运维条目、可重复登记、重启后仍在、运维优先、损坏状态拒绝启动、码过期与清扫、
铸造循环不涨内存、登记体校验、状态文件不含私钥）。变异验证：去掉码的单次性、去掉运维条目
保护、让 dry run 执行命令、先删配置再通知中继——四处都让对应测试失败。

Go 全包、Node 134 项、Swift 107 项通过。
 2026-09-17 13:28:32 +08:00
chick b5f548f1ad feat(agent): 配对窗口可显式绑定地址，默认仍是内网可达 
配对窗口是 agent 唯一持有的监听端口，而它授予的是设备信任：谁能带节点密码打到
/provision，谁就拿到一把 agent 会听命的密钥。此前它固定绑所有接口，且没有任何办法
收窄——一台本身能从公网路由到的节点（公网 VPS 上的 SimAdmin、放在非可信网络里的
设备）在窗口开启期间就把这个面暴露给了整个互联网。

现在加 --pair-bind，只接受 IP 字面量。不接受主机名是刻意的：绑定时解析名字意味着
监听地址取决于 DNS 当时说什么，那不是运维做过的决定。

默认值仍是绑所有接口，这个我改过一次又改回来了，原因值得记下来：我先把默认设成
127.0.0.1 并写了理由，然后发现配对按设计走内网、手机要直接打到节点，回环监听从
另一台机器根本连不上——那不是一个加固措施，而是一个永远不工作的流程，用户对这个
功能的第一次体验会是"连接被拒"且没有解释。所以默认保持内网可达，把"节点能从公网
路由到时请收窄"写进部署文档，并在 --pair-bind 上给出显式入口。

测试断言默认值同时满足两件事：是 IP 字面量（不是名字），且不是回环（手机要能连）。

Go 全包、Node 120 项、Swift 107 项通过。
 2026-09-17 07:47:25 +08:00
chick e2d4ea317c fix(agent): 设备列表在运行中重读，使吊销无需重启即生效 
文档写的吊销路径是：在节点上跑一次 `--pair`，POST /destroy，节点的下一次
握手就把该 bearer 从中继路由里摘掉。这条路径此前不工作：daemon 只在启动时
读一次设备列表，于是它既继续接受被吊销手机的签名，又在下次握手时把那个
bearer 重新报给中继——吊销被节点自己撤销。唯一能让它生效的办法是重启
服务，而文档没有这么说。

各组件单独看都是对的：文件确实被写空了，push 确实发出去了，中继确实应用了。
坏的是"运行中的进程再也不看那个文件"这件事，而单元测试看不见它。

现在 internal/config/live.go 的 LiveDevices 每个轮询周期重读一次配置：按
mtime、大小与 inode 判断变化（一次 stat，未变则零 I/O），变了就强制重新
握手，让中继拿到新的集合。inode 是必要的：Save 走临时文件加重命名，而
"配对后立刻 destroy"这种连续写入会落在同一个时钟刻度里，只有 inode 能区分。

读取失败保留当前集合而不是清空。清空是最坏的结果——一次瞬时文件系统错误会
把该节点所有已配对的手机锁在门外，而用户必须跑到节点上才能修。

测试：
- internal/config/live_test.go 六项：destroy 与新增设备都能被察觉、未变化时
  不误报（误报会每个周期强制握手，而每次握手都会顶掉挂起的 poll）、同一秒内
  的变化、读取失败保留集合、不可用的密钥被拒。
- test/revocation.test.js 跑真实二进制：在它脚下改配置文件，断言中继侧的设备
  数归零且该 bearer 不再可路由，节点仍在线。它需要 go 与 openssl，缺任一则
  跳过并说明原因。变异验证：去掉重读，测试失败。

顺带修掉一个只在 sudo 配对时暴露的缺陷：config.Save 用临时文件加重命名，
在 root 下会把配置文件变成 root 所有，而 systemd 单元以 msa-agent 用户运行，
于是配对看起来成功、节点重启后读不到自己的配置。现在重命名前保留原文件的
uid/gid，无法保留时报错而非警告。

文档同步：部署文档说明 destroy 在一个轮询窗口内（默认 24s）生效且无需重启；
架构文档把"仍需内网"改写为准确的边界——本地吊销已修好，不碰节点的远程吊销
（中继下发受信集快照）仍未做，那才是丢手机场景真正的短板。

Node 94 项、Go 全包、Swift 99 项全部通过。
 2026-09-16 23:43:45 +08:00
chick 09ccc67799 fix(relay): 校验 agent 握手签名、判定 agent 断线、保住跨重握手的邮箱 
三处都是"每个组件各自正确、合起来坏了"的接缝缺陷，其中第一处按部署文档
配置时必然命中。

1. 中继没有校验握手签名的能力。校验器被设计成 agent 条目上的 verify 回调，
   而所有测试都注入了桩，于是唯一真实存在的校验器就是那些桩：按
   docs/deployment.md 写的配置里没有它，第二次 hello 抛
   "agent.verify is not a function"，对每台节点回 500。现在配置只接受
   signKey（base64 Ed25519 公钥），中继自己验签，能验不能签；密钥缺失、
   长度不对或非规范 base64 一律拒绝启动——一个启动后拒绝全机群的"健康"
   中继比启动失败更难查。msa-keygen 的输出与部署文档同步补上该字段。

2. agent 断线后中继永远认为它在线。此前只有进程关闭才 detach，而节点被杀、
   断电、拔网线留下的只是一个关闭的 socket：节点会永远在线，手机的每条请求
   白等 30 秒并收到"节点可能已执行"——实际没有任何东西在监听。现在长轮询的
   socket 断开即判定离线（比对 session token，避免陈旧连接顶掉新会话），
   实测从 504/30009ms 变为 503/5ms。

3. 重新握手丢弃邮箱。attach() 整体替换节点记录，连带丢掉已排队的信封，
   于是重连窗口内到达的请求被静默丢弃、手机 5 秒后收到"节点离线"，而节点
   其实刚连上。重握手在每次会话过期与每次重连都会发生，是常规路径而非边角。
   现在邮箱与每个信封的 handover 期限跨重握手保留。

同时修掉同一节点第二个长轮询孤儿化第一个的问题：两个 poll 共用槽位，后到的
覆盖先到的 resolve，前一个 promise 永不 settle、HTTP 请求一直挂着。现役
agent 串行轮询碰不到，--once 与守护进程同跑就会命中。现在每个 poll 有自己的
槽位，被顶掉的那个立刻以空结果返回。

测试新增三个文件，并全部改用真实密钥（verify 桩已消失）：

- test/config.test.js 只经 start() + 环境变量启动中继并完成握手。第一个缺陷
  能存在，正是因为没有任何测试走这条装载路径——e2e.test.js 自己构造
  createRelay 参数，把配置装载整个绕过了。
- test/liveness.test.js 七项节点生死与重连性质，两个方向的错误都断言：
  漏判（死节点永远在线）与误判（陈旧 socket 顶掉新会话）。
- test/hello.test.js 把握手签名的字节直接与 Go 源码里的字面量比对，并断言
  NUL 分隔符两侧一致——这是 relay 与 agent 之间唯一没有共享代码可依赖的地方。

四处修复都做了变异验证：改回旧行为后对应测试必失败。

Node 82 项、Go 全包、Swift 99 项、端到端（真编译运行 Go agent 经 TLS 接真中继）
全部通过。
 2026-09-16 22:55:49 +08:00
chick f8277791a9 feat: 端到端测试（真 agent + 真中继 + TLS），并修三处只有它能发现的缺陷 
新增 test/e2e.test.js：编译并运行 Go agent，经 TLS 接到真中继，由模拟手机发起
签名请求，再断言节点实际收到的内容（含 audit 日志不含 body/密码、危险写 body
逐字节一致）。缺 go/openssl 则跳过并说明原因。

它一次抓出三个单元测试各自都通过、合起来却坏了的问题：

1. transport.Client 把会话 token 写进 c.token，而 c.token 是 bearer——Poll/Result
   因此用会话 token 当 bearer 发出，中继一律 401。现象是 agent 连上后无限重连，
   日志说'凭据被拒'。现在两个凭据分成两个字段，并加测试断言握手带 bearer 不带会话、
   轮询带会话。
2. main.loop 每个周期都重新握手。中继每个节点只保留一个会话，新握手会顶掉旧的并
   丢弃其挂起的轮询，于是两次握手之间到达的请求被投进已不存在的会话、以'agent 离线'
   超时——而 agent 全程在线。改为只在会话失效/传输失败时重新握手。
3. auth.registerDevices 把'已存在'一律跳过，随后又被'本轮未声明'的回收循环删掉，
   所以节点的第二次握手会把自己注册的设备全部注销。改为本节点已持有即确认（幂等）。

另：transport 支持 relayCAFile（PEM 钉 CA，替代系统信任库，不是关闭校验），
测试用自签证书 + 钉 CA 走真实 TLS 校验路径。
 2026-09-16 20:17:01 +08:00
chick 1f46b7000d feat: 部署文档与单元文件；P6 渗透自查并修复一处真实缺陷 
- docs/deployment.md：中继（反代要点含长轮询超时）、agent（msa-keygen 生成配置）、
  配对窗口、按拒绝原因分流的排障表
- agent/cmd/msa-keygen：生成节点密钥、nodeID、agent token 与配对秘密，打印中继注册条目；
  不生成设备密钥（那是手机的事，能生成就能冒充）
- relay/systemd/simadmin-relay.service：保护指令与 agent 单元的差异逐条写明
  （无 MemoryDenyWriteExecute，因为 V8 JIT 需要 W+X 页）
- test/adversarial.test.js（12 项）：回环硬校验（结构性断言中继无出站路径）、
  重放与新鲜度的责任划分、邮箱深度与 handover、设备注册越权、信封校验边界
- 修 registry.resolve 未校验 nodeID：pending 表只按 reqID 索引，被控节点知道
  另一节点的在途 reqID 即可抢先应答使其变 orphan，合法应答被丢弃
- .gitignore 排除交叉编译产物
 2026-09-16 19:20:59 +08:00
chick 3de2736882 feat: 规范化 JSON 与三语言互验加固；app-routes 生成器 
- wire.CanonicalJSON 自己写字符串转义：Go 编码器即使在关闭 HTML 转义时仍会转义
  U+2028/U+2029，而 Node 与 Foundation 输出字面量；两处拼写解码结果相同，
  因此签名不同却看不出原因。孤立代理项改为显式拒绝（Go 会替换成 U+FFFD、
  Node 保留转义文本、Foundation 直接解析失败，三种行为只能取交集为空）
- 对象键排序按 UTF-8 字节序（Go 的 sort.Strings 语义）；Node 参考实现改用
  Buffer.compare，因为 Array.sort 的 UTF-16 码元序在星形平面边界上与之相反
- test-vectors.json 新增转义、键序与必须拒绝的输入；Go/Node 双向断言
- 新增 scripts/export-app-routes.swift 生成 contracts/app-routes.json，
  补上此前 vendored 路由表靠手抄的一环
- README 记录 iOS 侧向量校验为何是'互相验证'而非'逐字节相同'（CryptoKit
  的 Ed25519 签名随机化）
 2026-09-16 18:57:06 +08:00
chick 78e0d303ab feat: 配对管理端点与中继侧设备注册上报 
- agent --pair：临时监听 :3001 仅开放 /provision 与 /destroy，以节点密码为共享秘密；
  窗口由三个独立条件关闭（首次成功配对 / 失败尝试 10 次 / 10 分钟超时），配对成功后
  管理监听即关（设计 §7 第 4 步）
- agent 为每台配对手机生成中继 bearer（config.Save 0600 原子写；启动时为手写条目补发）
- transport.PushDevices：握手成功后全量上报本节点受信设备集；空集是吊销声明而非无操作
- relay /v1/agent/devices：agent 会话后鉴权的设备注册；全量替换本节点条目；
  操作员 MSA_DEVICES 为 static 不可被覆盖；跨节点 id 不可抢占
- 中继设备注册替代了 §11 第 6 项的一部分：节点 destroy + 重握手即可在路由层吊销
- 配置：provisionSecret 字段（无密码保护节点需显式设置才可配对）；Validate(pairMode)
- 测试：pair 流程 8 项、设备注册 6 项、transport 1 项；文档 §7 实现修订注记与 README 状态
 2026-09-16 11:43:52 +08:00
chick 443af20e0a feat: agent 本机 SimAdmin 登录与会话维持；中继设备侧限流与 agent Retry-After 
- runtime.NodeAuth：agent 自查 /api/auth/status，需要时自行 POST /api/auth/login 并持
  simadmin_session Cookie 转发；错误密码进入 60s 冷却（对齐控制台 ensureAuthenticated），
  节点回 401/403 即失效重探，SimAdmin 重启无需重启 agent
- 节点密码进 agent 配置（nodePassword），永不经中继、永不下发到手机；登录路径仍被策略
  挡在电话可达面之外（TestAuthPathsAreUnreachable）
- 新拒绝分类 node_auth_failed：与 upstream_error 区分，手机可提示'该节点需重新配置'
- 中继：/v1/request 每设备固定窗口限流（默认 30/分钟），未鉴权调用不消耗预算
- transport：解析 Retry-After 并入退避；main loop 对 429 直接遵从中继指示
- contracts/envelope.schema.json 补 InnerResponse.outcome 字段
- 设计文档与 README 同步：WSS 改为长轮询的实现修订、响应方向已临时×临时、P2/P3 状态
 2026-09-16 09:15:25 +08:00
chick 54d9696a4d baseline: P1 契约、agent 核心与中继投递（既有工作首次入库） 2026-09-16 08:41:13 +08:00