oxidezap/whatspec
GitHub: oxidezap/whatspec
从 WhatsApp Web 的 JS bundle 中提取协议接口并生成语言无关的 IR，供第三方客户端或库构建使用。
Stars: 5 | Forks: 0
# whatspec
**从 WhatsApp Web 的 JavaScript bundle 中提取其协议接口，并生成语言无关的 IR（以及参考 Rust 代码）—— 供任何客户端/库在此基础上构建。**
WhatsApp Web 将其整个协议（IQ stanzas、protobuf schemas、GraphQL operations、app-state actions、feature flags、wire enums）编译到一个巨大的、经过压缩的 JS bundle 中。`whatspec` 使用 [`oxc`](https://oxc.rs) AST 解析该 bundle，并在 [`generated/`](generated) 下生成干净、带版本号且确定性的中间表示（IR）。该 IR 就是契约 —— 可以从 Rust、Go、TypeScript、Python 或任何其他语言来消费它。仓库中提交的 Rust 模块只是一个*参考*消费者，而不是核心目的。
## 它提取的内容
| 领域 | `generated/…` | 它是什么 |
|---|---|---|
| **iq** | `iq/index.json` (+ Rust) | `` 请求构建器和响应解析器，按 namespace 划分 |
| **proto** | `proto/WAProto.proto` | protobuf schemas，以 `.proto` 文件的形式呈现 |
| **mex** | `mex/index.json` (+ Rust) | Relay/GraphQL persisted operations（doc id、kind、类型化变量/响应） |
| **appstate** | `appstate/index.json` (+ Rust) | app-state (syncd) action schemas 和索引 |
| **abprops** | `abprops/index.json` (+ Rust) | A/B-props feature-flag 注册表（约 1.7k 个 flags：code、type、default） |
| **enums** | `enums/index.json` (+ Rust) | wire-enum 目录（nack codes、chat/receipt types 等） |
每个领域都会在 `generated/schema/` 下附带一个 JSON Schema，顶层的 `generated/manifest.json` 会记录 WhatsApp 版本、各领域的计数、内容哈希以及提取诊断信息。
## 快速开始
```
# 获取当前的 web.whatsapp.com bundle 并（重新）生成所有内容：
cargo run --release -p whatspec -- update
# …或处理你已有的 bundle（离线）：
cargo run --release -p whatspec -- update --bundles ./my-bundles
# Version-keyed cache：当远程 version 未更改时跳过下载：
cargo run --release -p whatspec -- update --cache .wa-cache
# 比较两个生成的输出（例如跨越 WhatsApp version bump）：
cargo run --release -p whatspec -- diff old-generated/ generated/
```
`update` 默认是安全的：如果任何领域的覆盖率下降，它会拒绝覆盖已提交的输出（传入 `--allow-shrink` 可接受真实的缩减），并且如果某个领域没有提取到任何内容，它会明确报错。
## 消费 IR
中立产物是 `generated//index.json`，由 `generated/schema/.schema.json` 进行验证。将你自己的 codegen 指向这些文件 —— 这些 schema 在 WhatsApp 发布的各个版本中都是稳定的（`schemaVersion`），独立于不断变化的 `waVersion`。
Rust 消费者也可以直接使用已提交的参考模块；它们仅依赖于 `serde`，并且支持 tree-shakeable（你只需为你引用的内容买单）。
## 设计
- **确定性：** 相同的 bundle 始终生成字节一致的输出（稳定的排序键，没有偶然的顺序）。
- **无 C 依赖：** 纯 Rust 实现（通过 rustls + RustCrypto 进行 TLS，通过 `sha2` 进行哈希处理），在 CI 中强制执行。
- **WASM 友好：** IR crate 和 bundle 发现层可编译为 `wasm32`，因此基于浏览器的 fetcher 可以复用它们。
## 免责声明
`whatspec` 是一个独立项目，**不附属于、也不受 WhatsApp LLC 或 Meta 认可或赞助**。“WhatsApp” 是其各自所有者的商标，此处仅出于描述性目的使用，用于标识本工具与之互操作的协议。
## 许可证
MIT © 2025 João Lucas de Oliveira Lopes —— 详见 [LICENSE](LICENSE)。
标签：AST解析, Rust, WhatsApp协议, 中间表示, 云资产清单, 协议提取, 可视化界面, 网络流量审计, 逆向工程, 通知系统