CLI密码学【免费下载链接】magic-wormholeget things from one computer to another, safely项目地址https://gitcode.com/gh_mirrors/ma/magic-wormhole点击查看免费下载magic-wormhole 是一个在两台电脑之间安全传输文件/文本的开源工具其核心设计是让两端用户说出同一句魔法口令code即可建立一条端到端加密的数据通道。本文以仓库根目录的 NEWS.md 为主线系统梳理该工具从 0.2.0 初始版本到 0.24.0 的完整版本演进包括 CLI 命令的诞生与重构、Tor/QR 码/Dilation 等关键能力的引入、两起路径遍历漏洞CVE的修复过程以及程序化 API 的多次破坏性变更。读完本文你将理解 magic-wormhole 每个核心特性为什么存在、何时出现、如何实现并能依据版本差异安全地升级或选择正确的使用方法。一、版本总览一条持续十余年的演进线NEWS.md 记录了从 2015 年 4 月的 0.2.0初始版本到 2026 年 5 月的 0.24.0 共二十余个版本的变更。整体演进可分为四个阶段协议奠基期0.2.0 ~ 0.8.x确立口令交换 中继 PAKE的对称协议完成 CLI 子命令体系send/receive/ssh、WebSocket 连接、目录打包传输等基础能力稳定与生态拆分期0.9.x ~ 0.13.0Tor 支持重写、转口中继Transit Relay与邮箱服务器Mailbox Server拆分为独立仓库、Python 2.7 停止支持、首个安全修复恶意文件名清洗落地Dilation 落地期0.12.0 ~ 0.20.0实验性 Dilation 协议引入并逐步成熟新增状态反馈 API、Ping/Pong 超时、命名子协议named subprotocol与子通道组合能力安全加固与现代化期0.21.x ~ 0.24.0修复两起路径遍历漏洞CVE-2026-42448 及其前序回归、排除有问题的 Autobahn 依赖、二维码默认展示、Bash 4 补全等。从源码结构看当前仓库 src/wormhole/ 下的模块布局正是这些版本演进的沉淀结果_mailbox.py邮箱消息、_key.py密钥派生、transit.py大块数据传输、_dilation/新一代传输协议等。二、CLI 命令体系的成型史2.1 从一个可执行文件到子命令 别名早期版本0.7.5 之前CLI 通过单一wormhole可执行程序区分 send/receive 模式。0.7.5 起包同时安装wormholesend/receive与wormhole-server中继服务器两个可执行文件。0.8.1 引入 Click 参数解析并带来短别名wormhole tx等价于wormhole sendwormhole rx等价于wormhole receive0.8.2 又接纳recv作为receive的别名to help bad spelers。这些别名至今仍保留在 src/wormhole/cli/cli.py 中ALIASES { tx: send, rx: receive, recieve: receive, recv: receive, }2.2 顶层参数与子命令参数的分工0.8.1 关键变更0.8.1 将大多数参数从wormhole 命令挪到子命令上。按当前 cli.py 的实现顶层仅保留四个参数参数默认值说明--appid无自定义应用 ID供脚本/包装程序使用0.9.0 加入--relay-url公共中继地址见public_relay.RENDEZVOUS_RELAY邮箱中继服务器 URL支持wssTLS0.12.0 起--transit-helper公共转中继地址见public_relay.TRANSIT_RELAY大块数据传输中继--dump-timing无调试将事件时间线写入 JSON 文件0.7.0 引入其中--relay-url与--transit-helper均支持环境变量WORMHOLE_RELAY_URL、WORMHOLE_TRANSIT_HELPER0.10.4 加入。wormhole send的子命令参数包括--code人工指定口令、--text发送文本-表示从 stdin 读取、--ignore-unsendable-files0.10.0 加入跳过不可读文件/悬空符号链接、--verify展示验证串并等待人工确认、--code-length口令长度默认 2 个单词、--qr/--no-qr0.18.0 起默认展示二维码可用环境变量WORMHOLE_QR控制、--debug-state调试状态机迁移可选机器为B,N,M,S,O,K,SK,R,RC,L,C,T。wormhole receive的独有参数包括--output-file/-o覆盖接收文件名/目录0.6.1 实现、--only-text/-t拒绝文件传输、--accept-file跳过确认自动接受0.18.0 加入支持环境变量WORMHOLE_ACCEPT_FILE、--allocate/-a分配新口令而非输入0.13.0 加入。0.10.3 起wormhole help与wormhole --help行为一致0.20.0 还新增了magic-wormhole作为 CLI 入口命令。2.3 口令输入与 Tab 补全接收端支持 Tab 补全输入口令wormhole receive若检测到用户未使用 Tab 键会提示 (note: you can use to complete words)0.9.2 起。0.8.1 起 Tab 补全在 OS-X 自带 Pythonlibedit下也能工作。底层实现见 cmd_receive.py 中的input_with_completion。0.10.3 起会在入口处拒绝非法口令含空格或非数字前缀。2.4 零模式zeromode与分配口令-0/--zeromode使用固定口令0-进入无口令模式receive --allocate则让接收端反向分配口令随后发送端可用wormhole send --code code连接0.13.0 加入。分配成功后接收端会打印提示Allocated code: code On the other computer, please run: wormhole send --code code filename注意 cli.py 中做了参数互斥校验使用--allocate时不能再传 code--code-length必须与--allocate搭配。三、数据传输能力的时间线3.1 文件、文本与目录0.6.1开始支持发送/接收整个目录传输前打包为 zipfile0.10.0wormhole send DIRECTORY支持大于 2GB 的目录但当时 zipfile 仍在内存中构建受可用内存限制0.12.0真正用tempfile将大目录的 zipfile 写到磁盘上修复了一个五年历史、导致大于可用内存的目录传输失败的 bug0.14.0目录打包改为流式压缩streaming compression配合 cmd_send.py 中基于zipstream.ng的ZipStream实现0.13.0接收目录时超过 10MB 才落盘SpooledTemporaryFile(max_size10*1000*1000)见 cmd_receive.py。3.2 块设备发送0.12.0wormhole send /dev/fd0可以发送命名块设备U 盘、SD 卡、软盘等对端收到的是普通文件。该逻辑位于 cmd_send.py通过stat.S_ISBLK判断设备类型后按文件方式读取。3.3 传输确认与校验发送端在数据发送完毕后等待接收端回执ack其中包含 SHA-256 哈希{ack: ok, sha256: hex}见 cmd_receive.py。发送端比对本地计算的哈希与对端回传值不一致则报 Transfer failed (bad remote hash)见 cmd_send.py。3.4 进度条与磁盘空间检查0.7.6 起使用tqdm渲染进度条可用--hide-progress关闭0.19.0 修复了进度条尺寸自适应问题0.9.0 起wormhole receive会在空间不足时拒绝传输estimate_free_spaceWindows 上不可用0.12.0 起接受此文件的默认答案从 no 改为 yes。四、安全演进从漏洞修复到防护机制4.1 恶意文件名清洗0.13.0SECURITY0.13.0 修复接收端显示中的怪异字符问题#476对接收端展示的文件名进行清理。相关防护在 cmd_receive.py 中有明确注释对repr()的使用至少部分是为了防御可能干扰终端显示的恶意文件名。4.2 路径遍历漏洞与 CVE0.21 ~ 0.24SECURITY 重点这是近期版本中最重要的安全内容NEWS.md 明确记录了两起漏洞0.23.02026-03-10ikmckenz 发现一次回归删除了basename()的使用使接收端暴露于路径名遍历攻击path-name traversal影响 0.21 与 0.22 两个版本。修复已随 0.23.0 发布并附带单元测试0.24.02026-05-05marduc812 发现当接收端通过--output指定了一个已存在的目录时同样存在缺失basename()的问题编号 CVE-2026-42448。缓解措施是确保--output指向的路径不是已存在的目录并升级到修复版本。当前源码中的防护逻辑位于_decide_destname()cmd_receive.py无论是否使用--output-file最终目标路径都会经过os.path.basename(destname)清洗当--output-file指向已存在目录时接收文件会被安全地放入该目录内部而不覆盖整个目录树。代码注释明确写道the basename() is intended to protect us against ~/.ssh/authorized_keys and other attacks。仓库测试 test_cli.py 提供了成体系的回归验证_decide_destname(file, ../../evil.txt)必须被清洗为提取目录下的evil.txtL1233test_existing_destdir_malicious验证对已存在输出目录传入../../../destination_file也不会逃逸L1254-L1269test_destdir_traversal使用 Hypothesis 属性测试随机生成含..的路径段组合断言_decide_destname的返回路径永远在基础目录之内L1282-L1310。4.3 zipfile 解压防护接收目录解压时_extract_file()cmd_receive.py会校验解压目标不得逃逸出extract_dir否则抛出 malicious zipfile 异常同时手动恢复 zip 内记录的文件权限位external_attr 16因为 zipfile 模块本身不恢复权限。4.4 其他安全相关变更0.8.2目标文件已存在时不向发送端泄露该事实仅回复 transfer rejected0.9.1中继服务器支持--blur-usage关闭连接日志0.6.x 起服务器可模糊化文件大小、粗化时间戳0.10.1/0.10.2服务器默认不再主动广播 CLI 版本避免不必要的升级提醒WebSocket 连接错误改为可读报错而非automat._core.NoTransition崩溃0.13.0所有历史版本二进制签名全部提交进 Gitsignatures/目录因为 PyPI 停止提供分离签名文件——这在 signatures/ 中可以看到从 0.7.0 到 0.24.0 的.asc文件0.21.0当用户代码要求时对不需要的入站子协议产生错误0.22.0 在连接丢失时对挂起的receive_record()调用执行 errback。五、Tor 支持从试验到默认依赖Tor 能力经历了三个阶段0.7.0初步pip install magic-wormhole[tor]后运行wormhole --tor send自述不稳定且缺乏测试0.9.2重写wormhole send、receive、ssh invite、ssh accept统一接受三个参数--tor所有连接走 Tor 并隐藏 IP、--launch-tor自行启动 Tor 进程、--tor-control-port指定控制端口。当时的限制是仅支持 python2.7、需安装[tor]extra0.10.0默认依赖txtorcon成为默认依赖移除[tor]extra只要系统装有 Tor 可执行文件即可用Tor 同时支持 py30.10.4 修复了此前完全失效的--tor-control-port未指定时先尝试默认控制端口再回退到默认 SOCKS 端口。当前 CLI 中的 Tor 参数定义见 cli.py实际连接管理位于 tor_manager.py测试 test_tor_manager.py 覆盖相关逻辑。六、Dilation新一代传输协议Dilation 是 NEWS.md 中反复出现的技术主线值得单列一节。6.1 从实验到 API 定型0.12.02020-04引入不完整的 Dilation 实验实现#312目标是实现断点续传、网络地址变化容忍、长驻 GUI/守护进程中的双向传输。当时协议未定稿、与旧 Transit 协议不兼容、无 CLI 入口代码仅用于防回归与开发0.19.02025-05为 Dilation 增加状态反馈API#591并用该 API 在代码被对方使用时通知发送端#575新增 Ping/Pong 超时以加速重连#590改进版本协商#606/#611测试套件全面迁移到 pytest#603/#6100.20.02025-07INCOMPAT——Dilation 扩展现在支持子通道subchannel组合每个子通道有命名子协议named subprotocol并配套新 API同时移除了通用的 control 子通道Dilation 状态更新中附带hints信息转中继提示。6.2 命名子协议与子通道 API当前 src/wormhole/_dilation/manager.py 中DilatedWormhole提供两个核心方法L75-L107listener_for(subprotocol_name)返回IStreamServerEndpoint用于监听指定名称的新子通道listen()后每个新连接都会调用所给 Factory 的buildProtocol()connector_for(subprotocol_name)返回IStreamClientEndpoint用于向对端发起指定子协议的连接对端会看到一个 OPEN 并实例化对应的 listener。集成测试 test_dilate/test_full.py 展示了真实用法eps1.listener_for(proto).listen(fserv0)配合eps2.connector_for(proto).connect(f2)建立单子协议通道L52-L79以及在同一链路上承载hello/bonjour两个不同名称子协议的test_double_subprotocolL97-L136。6.3 Dilation 版本协商Dilation 版本号以《地海传说》中的巫师命名当前为[ged]manager.py。双方通过can-dilate版本列表取交集选择最佳版本_find_shared_versionsL168-L189若对端不支持 Dilationw.dilate()会在收到 VERSIONS(KCM) 后 errbackL155-L156。6.4 状态反馈 API0.19.0 引入的 Status API 定义在 src/wormhole/_status.py通过类型联合表达邮件箱连接状态Disconnected | Connecting | Connected | Failed | Closed、密钥状态NoKey | AllegedSharedKey | ConfirmedKey、口令状态NoCode | AllocatedCode | ConsumedCode以及 Dilation 专用的对端连接状态NoPeer | ConnectingPeer | ConnectedPeer | ReconnectingPeer | StoppedPeer。发送端在 cmd_send.py 中通过on_status_update回调订阅状态当口令从AllocatedCode变为ConsumedCode时向用户打印 Note: code has been consumed and can no longer be used.——这正是 0.19.0 中使用状态 API 在口令被消费时通知发送用户的落地实现。七、SSH 公钥互传wormhole ssh invite/accept0.8.2 加入实验性的wormhole ssh invite与wormhole ssh accept子命令用于安全地把你的~/.ssh/id_*.pub公钥追加进远端~/.ssh/authorized_keyswormhole ssh invite [--user USER]等待对方发送公钥wormhole ssh accept CODE [--key-file/-F PATH] [--yes/-y]发送指定公钥未指定时若~/.ssh/*.pub唯一则自动选择多个则交互询问。实现见 cli.py 与 cmd_ssh.pyfind_public_key()负责枚举.pub文件并解析出kind / keyid / pubkey三元组发送前默认要求确认。0.13.0 还修复了带注释的 SSH 密钥解析问题#434。八、程序化 API 的破坏性变更史NEWS.md 反复强调1.0 之前 API 不稳定开发者在升级客户端代码时需注意以下断点0.4.0协议改为对称形式内部布局重排所有import wormhole的应用必须更新0.8.0完全协议重写.send_data()/.get_data()改为.send()/.get()且不再接受 phase 参数Wormhole 成为记录管道.get_verifier()改为.verify()并等待密钥确认消息Wormhole 由函数调用构造而非类构造close()总是等待服务器对出站消息的 ack0.10.0客户端代码用 Automat 状态机完全重写附带Journaled Mode日志模式铺垫详见 docs/journal.rst0.19.0打包变更sdist 文件名改用下划线magic_wormhole-0.19.0.tar.gz原因是 setuptools v69.3.0 于 2024 年实现了 PEP 625。中继服务也同步演进0.11.0 将 Rendezvous Server更名 Mailbox Server拆分为独立仓库magic-wormhole-mailbox-server0.10.4 将 Transit Relay 拆分为magic-wormhole-transit-relay。运行自有服务器需分别pip install这两个包当前客户端仅为测试导入它们。九、性能、可用性与依赖治理启动速度0.10.5升级 python-spake2 后不再为未使用的参数集计算盲化因子Raspberry Pi 3 上wormhole --version从约 19 秒降到 7 秒长连接保活0.8.1双方定期发送 keep-alive 消息防止 NAT/防火墙因空闲断开导致双方永久挂起长时间等待0.6.0增加密钥确认消息避免接收方输错口令时发送方一直挂起0.12.0 修复双方同时--verify时接收方无法展示验证串的死锁#349转中继优先级0.9.1--transit-helper tcp:host:port:priority2.5支持数值优先级双方交换中继建议后优先尝试最高优先级中继直连永远优先于中继依赖排除0.21.0 排除 autobahn 24.9.1/25.10.10.21.1 排除 25.10.2Windows 故障0.22.0 排除 25.11.1/25.12.1——这是 Autobahn 发布质量问题引发的连锁治理Python 版本策略0.13.0 弃用 Python 2.7 与 3.5/3.60.18.0 弃用 3.80.19.0 弃用 3.9 并将 CI 迁移至 GitHub Actions0.20.0 全面清除 Python 2 痕迹移除u前缀、type()调用改为直接使用类、格式化字符串改为 f-string。十、运维与打包服务器参数0.10.3wormhole-server start新增--relay-database-path、--stats-json-path、--websocket-protocol-option--disallow-list可禁用 nameplate 列表请求即禁用口令数字前缀的 Tab 补全同时让 DoS 更易检测0.10.0提升 RLIMIT_NOFILE 以容纳更多并发连接crowded拥挤邮箱会直接向客户端返回错误0.10.3客户端据此提示用户重新生成口令而非反复重连错误文案见 cli.py命令行补全0.14.0为 bash、zsh、fish 提供补全文件见仓库根目录的 wormhole_complete.bash、wormhole_complete.zsh、wormhole_complete.fish0.21.0 新增面向 macOS 的 Bash 4.0 补全补丁 bash-completions-version-4.patch打包渠道0.9.2 加入 snapcraft 打包配置snapcraft.yaml0.18.0 支持 PEP 518pyproject.toml0.19.1 修复 sdist 中测试运行与测试服务器版本号报告问题调试利器--dump-timingFILE.json可记录双方事件时间线并合并分析延迟0.7.0配套可视化脚本见 misc/dump-timing.py--debug-state可观察 Automat 状态机迁移轨迹。十一、升级建议与兼容性速查依据 NEWS.md 的兼容性声明可按以下原则规划升级协议兼容0.8.0 与 0.7.x 完全互不兼容但老客户端察觉不到新客户端0.9.x 起转中继要求双方均 ≥ 0.9.0其余相邻版本大体保持前后兼容必须升级的安全版本0.13.0文件名清洗、0.23.0路径遍历回归修复、0.24.0CVE-2026-42448 修复——尤其当你会用wormhole receive --output指向已存在目录时依赖锁定若受 Autobahn 发布问题困扰优先升级到 0.22.0已排除 25.11.1/25.12.1Python 版本当前版本要求 Python ≥ 3.100.19.0 起弃用 3.9API 使用者若你的代码依赖 0.7.x 之前的.send_data()/.get_data()等接口需按 0.8.0 的 API 文档迁移Dilation 子协议 API0.20.0 定型仍属实验性质版本命名与行为可能继续调整。如需深入某一模块可直接阅读 docs/ 下的协议文档如 docs/client-protocol.rst、docs/file-transfer-protocol.rst、docs/dilation-protocol.rst、docs/transit.rst与对应源码 src/wormhole/将版本史与实现细节相互印证。赞分享CLI密码学【免费下载链接】magic-wormholeget things from one computer to another, safely项目地址https://gitcode.com/gh_mirrors/ma/magic-wormhole点击查看免费下载相关推荐Boilerplates CLI 版本演进全解从 0.0.4 到 0.2.0 的功能地图与迁移指南Boilerplates CLI 版本演进全解从 0.0.4 到 0.2.0 的功能地图与迁移指南 Boilerplates 是一个面向家庭实验室homelCLI开发工具代码生成git-bug 版本演进全解析从 0.2.0 到 0.10.1 的架构变迁与核心能力沉淀git bug 版本演进全解析从 0.2.0 到 0.10.1 的架构变迁与核心能力沉淀 git bug 是一个嵌入 Git 的分布式、离线优先缺陷追踪器。本开发工具研发协作containerd NRI 插件协议演进全解析从 0.2.0 到 0.4.0 的架构重写与迁移实战containerd NRI 插件协议演进全解析从 0.2.0 到 0.4.0 的架构重写与迁移实战 NRINode Resource Interface云原生容器运行时上一篇Mailtrain GDPR合规性用户数据保护与隐私政策配置终极指南下一篇Go语言高级编程CGO异常栈追踪调试跨语言问题的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
