wappie

Wappie 是一个具有密封存档的多租户 WhatsApp API 服务器，并配有一个调用相同 API 的 Web 客户端。它通过 HTTP 和 WebSocket 将业务系统连接到 WhatsApp，提供共享工作区、基于号码的权限管理以及消息客户端。其服务器、CLI、Web 客户端和基础管理功能采用 Apache-2.0 开源；托管服务和商业计费则单独维护，托管试点仅限邀请且免费，且其中的支付为模拟支付。 在功能上，该服务器通过终端使用八位代码（在“已链接设备”下输入）或在终端渲染的 QR 码来配对 WhatsApp 设备，随后对进入的设备流量进行密封。它支持历史记录同步、投影编辑、撤回和反应，记录回执，并跟踪每个阅读者屏幕上显示的修订版本。入站媒体按 Meta CDN 提供的方式原样存储，同时支持出站媒体的上传与发送，以及“一次性查看”功能。结构化内容（位置、投票、联系人、事件）、联系人、名称和个人资料图片、按需回填，以及包含未读数、勾选状态、在线状态、群组和投票的对话层均已实现。访问可通过 CLI 工具 (`wsctl`) 和 HTTP/WebSocket API 完成，提供托管端点和用于 WebSocket 的 `/v1/ws`。 存档保护模型是该项目的核心。WhatsApp 媒体在到达时已使用 32 字节媒体密钥通过 encrypt-then-MAC HMAC 进行 AES-256-CBC 加密；密文被原样存储，仅媒体密钥被密封至设备公钥。消息正文使用 HPKE (RFC 9180, X25519 + HKDF-SHA256 + AES-256-GCM) 在覆盖一批消息的内容密钥下进行密封，README 中解释这是基于成本而非吞吐量的考量。服务器仅持有公钥：它可以密封但不能解密。每个设备由配对它的客户端生成一对存档密钥；私钥部分被密封至每个可读取该设备的账户公钥（密钥授权），随后被删除。账户私钥在注册时于浏览器中生成，由绑定到账户地址且基于 Argon2id 派生的密钥进行封装，且永不传输；恢复代码会对同一密钥进行第二次封装。浏览器在页面内部执行 HPKE、内容密钥处理、消息正文、联系人名称、个人资料图片和附件的解密。 权限采用分层设计：API 密钥具有 `read`、`send` 或 `full` 范围；成员仅能访问授予其权限的设备；所有者或管理员可访问每个设备的信封，并能进行配对、授权、铸造密钥以及在设备“离散”和“响亮”模式之间切换；没有任何范围可以访问租户配置。第三方被授予服务账户——一个没有密码的密钥对，像普通人一样被授予设备，并通过充当该账户的 API 密钥进行访问。默认关闭保留策略；租户可以设置一个时间窗口，服务器每小时对消息、回执、群组事件和附件应用该窗口，而聊天记录和联系人则保留。可以将一个人从所有设备的存档中擦除，删除设备或重置存档会将其附件对象从存储中移除。日志在所有层级上都会掩盖标识符。 本地运行需要 PostgreSQL 18 或更高版本以支持 `uuidv7()`，且需要非超级用户角色，因为超级用户会绕过行级安全性 (RLS)。对象存储是可选的：若未配置，附件将在数据库中排队直到存储可用。`make dev-up` 目标可在 Docker 中启动 Postgres 和 MinIO。测试目标涵盖格式化、审核、布局、启用竞态的测试、浏览器客户端的类型检查和构建、覆盖率和模糊测试，且每个测试在独立的 Postgres schema 中运行。Web 客户端使用 Vite 构建至 `web/dist` 并由 `WS_WEB_DIR` 提供服务；Go 二进制文件中不嵌入任何内容，若无构建版本，服务器仅提供 API。在开发期间，Vite 服务器将 `/v1` 代理到 Go 端口，因为 WebSocket 处理器仅接受同源连接。 README 坦诚地陈述了限制，而非暗示超出交付的功能。在运行代码的活动服务器上，攻击者可以看到 Signal 解密、密封和存储之间传输的明文，因此静态密封保护的是被盗磁盘、泄露的备份或数据库转储，而非被攻破的进程。whatsmeow 会话存储必须对进程可读；任何窃取该存储的人都可以冒充设备并读取新消息，但无法读取存档。出站文本和出站媒体以明文传输，因为 WhatsApp 的上传仅接受明文；入站媒体在服务器端永不解密。附件元数据（类型、大小、尺寸、时长、哈希）和路由元数据（包括回执）是可读的，因此数据库转储会揭示社交图谱以及谁在何时阅读了什么，但不会揭示内容。撤销授权可阻止密钥被再次获取，但无法召回已解锁的副本，因为密钥存在于浏览器中。丢失所有访问路径将导致存档对所有人永久丢失。浏览器会话材料以密文形式存储在 IndexedDB 中，由不可提取的 WebCrypto 密钥加密，且客户端交付了内容安全策略 (CSP) 且不加载任何第三方 JavaScript。 状态表列出了已完成的阶段：从骨架、迁移和媒体加密，到配对、摄取、编辑/撤回/反应投影、媒体入站和出站、历史同步、媒体重试、联系人、按需回填、Web 客户端、每设备密钥和账户、对话层、隐身模式和配额，以及安全审计通过；管理控制台被列为下一步。跨实现的测试向量在 Go 中生成并由两种实现共同打开，包括负面案例（如将 blob 移动到另一行或以另一种类型呈现），从而确保浏览器客户端不会仅与自身达成一致。`seeddemo` 工具通过真实的摄取流水线写入一段小型虚构对话，以便在无需配对手机的情况下开发客户端。