Magic-Wormhole 邮箱服务器协议深度解析-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01059/article/details/148362449

Magic-Wormhole 邮箱服务器协议深度解析

magic-wormhole get things from one computer to another, safely 项目地址: https://gitcode.com/gh_mirrors/ma/magic-wormhole

协议概述

Magic-Wormhole 的核心在于提供了一种安全可靠的互联网通信机制。其邮箱服务器协议设计精巧，允许两个互不相识的终端通过共享密钥和邮箱进行加密通信。本文将深入剖析这一协议的工作原理和实现细节。

核心概念与设计理念

邮箱系统类比

协议设计灵感来源于北美邮局系统：

名称牌(Nameplate)：相当于邮局信箱的编号（如"4-purple-sausages"中的"4"）
邮箱(Mailbox)：实际存储和转发消息的容器，对应随机生成的长字符串标识
应用隔离：通过AppID实现不同应用间的隔离，格式推荐采用"域名/应用名"

这种设计既保证了可用性（短数字便于记忆），又确保了安全性（长随机字符串作为真实标识）。

通信机制详解

连接建立过程

WebSocket基础连接：
- 使用二进制模式传输
- JSON格式编码消息
- 自动重连机制（初始1秒，按1.5倍递增，上限1分钟）
绑定流程：
```
Client->Server: type=bind\nappid=demo\nside=b491c
Server->Client: type=welcome\nmotd=Hello World
```
- 首次通信必须发送bind消息
- 服务器回应welcome消息，可能包含：
  - 版本提示(current_cli_version)
  - 维护公告(motd)
  - 错误信息(error)

名称牌管理

分配机制：
- allocate命令获取最短可用名称牌
- allocated响应返回分配结果
- list命令查询所有已分配名称牌
生命周期：
- claim声明使用权
- release释放使用权
- 空闲超时自动回收

邮箱操作

打开邮箱：
- open命令订阅邮箱并标记为活跃
- 无显式确认，通过后续消息间接确认
消息传递：
- add命令添加消息(phase和hex编码body)
- message响应传递消息(包含side标识)
关闭处理：
- close命令终止连接
- 支持多种mood状态反馈：
  - happy：成功交互
  - lonely：无响应超时
  - scary：加密验证失败
  - errory：其他错误

消息类型全集

| 方向 | 类型 | 关键字段 | 触发响应 | |--------|-------------|------------------------------|----------| | C→S | bind | appid, side | - | | C→S | list | - | nameplates | | S→C | nameplates | nameplates: [{id: str},...] | - | | C→S | allocate | - | allocated | | S→C | allocated | nameplate | - | | C→S | claim | nameplate | claimed | | S→C | claimed | mailbox | - | | C→S | release | nameplate? | released | | S→C | released | - | - | | C→S | open | mailbox | - | | C→S | add | phase, body(hex) | message | | S→C | message | side, phase, body, id | - | | C→S | close | mailbox?, mood? | closed | | S→C | closed | - | - | | S→C | ack | - | - | | C→S | ping | ping: int | pong | | S→C | pong | pong: int | - | | S→C | error | error, orig | - |

持久化与可靠性

服务器保障：
- 所有消息持久化存储
- 数据库提交后才返回响应
- 重启后数据不丢失
客户端恢复：
- 支持连接中断后恢复
- 提供"日志模式"确保断续通信的进度保持

典型交互流程

完整的两端通信示例：

Alice->Server: allocate
Server->Alice: allocated(nameplate=4)
Alice->Server: claim(nameplate=4)
Server->Alice: claimed(mailbox=xyz123)
Alice->Server: open(mailbox=xyz123)
Alice->Server: add(phase="pake", body=...)
Bob->Server: claim(nameplate=4)
Server->Bob: claimed(mailbox=xyz123)
Bob->Server: open(mailbox=xyz123)
Server->Bob: message(side=Alice, ...)
Bob->Server: add(phase="version", body=...)
Server->Alice: message(side=Bob, ...)
(后续应用数据交换)
Alice->Server: close(mood="happy")
Bob->Server: close(mood="happy")