No description
  • TypeScript 100%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-11 03:27:48 +00:00
patches feat(cli): offline integrity + roaming restore via CLI (acceptance snapshot) 2026-11-11 03:27:48 +00:00
src feat(cli): offline integrity + roaming restore via CLI (acceptance snapshot) 2026-11-11 03:27:48 +00:00
.gitignore feat(cli): offline integrity + roaming restore via CLI (acceptance snapshot) 2026-11-11 03:27:48 +00:00
bun.lock feat(cli): offline integrity + roaming restore via CLI (acceptance snapshot) 2026-11-11 03:27:48 +00:00
CHANGELOG.md feat(cli): offline integrity + roaming restore via CLI (acceptance snapshot) 2026-11-11 03:27:48 +00:00
main.ts feat(cli): offline integrity + roaming restore via CLI (acceptance snapshot) 2026-11-11 03:27:48 +00:00
package.json feat(cli): offline integrity + roaming restore via CLI (acceptance snapshot) 2026-11-11 03:27:48 +00:00
README.md feat(cli): offline integrity + roaming restore via CLI (acceptance snapshot) 2026-11-11 03:27:48 +00:00
tsconfig.json feat(cli): offline integrity + roaming restore via CLI (acceptance snapshot) 2026-11-11 03:27:48 +00:00

wire-cli 0.1

Bun 脚本开发的 wire-rs 命令行客户端。

前置

  • Bun(bun --version)
  • 运行中的 wire-rs 后端,默认 http://127.0.0.1:3000;线上 https://wire.treeden.app/api/v8(带子路径,CLI 会保留)

快速开始

cd wire-cli

bun main.ts login --email alice@example.test   # 缺参数会交互提示,密码静默输入;首次登录自动注册本库设备
bun main.ts conversations list
bun main.ts conversations get <convId>
bun main.ts events                       # 实时消息流,Ctrl-C 退出(用绑定设备)

命令

login                                  登录,保存会话(POST /login + GET /self 验活;首次自动注册本库设备并备钥)
logout                                 登出并清除本地会话(保留 keystore 与设备绑定)
register --name N --email E --password P
                                       注册(POST /register → 201 用户 profile,无 access_token,仍需 login;重复邮箱 409 key-exists)
self                                   当前用户(GET /self)
search <keyword> [--size N] [--domain D]
                                       用户目录(GET /search/contacts:handle/名前缀匹配,`--domain` 默认 wire.treeden.app)
refresh                                刷新 access token(POST /access)
clients list                           设备列表(GET /clients;`add`/`mls-setup` 已移除,见下)
mls create --with UID ...               建 MLS 会话并首 commit 建组(落盘 group state)
mls one2one UID ...                     取或建确定性 1:1(新会话首 commit,否则外部 commit 入组)
mls join --conv ID ...                   外部 commit 入组(落盘 group state)
mls send --conv ID --text T ...          同步 epoch 后加密发送(自动续 token,落盘发送棘齿)
mls recv [--conv ID] [--live] ...        拉取并解密展示;断言每会话 seq 连续(缺号报缺行 id);--live 常驻(断线重连 + 去重 + Ctrl-C 存盘退出)
mls checkpoint --conv ID ...             P3 验签演练:seal→verify→4 种失败复现→revoke→重 seal→先验后拉覆盖检查
mls restore <code> [--tail N] [--all]  P4 恢复验链:输码(conv UUID/链接或真恢复码)→验 checkpoint→拉全行(进度)→seq 断言(advisory)→解密(最新先行;新库+join 手順,详见下)
mls recovery status|enable|backup|confirm  P4 盲备份:发码(展示一次)→封包上传→抄写确认转 active;unconfirmed 重 enable 即轮换(旧码废)
mls demo [--text T]                       脚本化 A→B(一次性 throwaway 号,内存 keystore)
conversations list [--size N] [--start UUID] [--ids a,b,...]
                                       会话列表(GET /conversations)
conversations get <convId> [--domain D]
                                       会话详情(GET /conversations/{id})
conversations list-ids [--size N]      会话 id 列表(POST /conversations/list-ids)
conversations fetch <id> [id...]       按 id 批量取详情(POST /conversations/list)
notifications list [--since ID] [--size N]
                                       通知 backlog(GET /notifications,用绑定设备)
notifications last                     最新一条通知(GET /notifications/last)
notifications get <id>                 单条通知(GET /notifications/{id})
events [--poll]                        实时消息流(WebSocket /await,--poll 切轮询;用绑定设备)
health                                 后端状态(GET /healthz + /api-version,免认证)

全局 flag(放命令前或命令后均可):--backend URL、--session-file PATH、 --json(强制原始 JSON 输出,列表默认表格)、--verbose(stderr 打印请求行)。

环境变量

变量 说明 默认
WIRE_CLI_BACKEND 后端地址(旧 WIRE_BACKEND 已废弃:设置仅打印 warning,不再生效) http://127.0.0.1:3000
WIRE_CLI_SESSION_FILE SQLite 单库文件(会话 + keystore + 游标;旧 .json 已废弃不读,删掉重登即可) ./.wire-session.db(存在时),否则 ~/.wire-cli-session.db
WIRE_CLI_EMAIL / WIRE_CLI_PASSWORD login 默认值(旧 WIRE_EMAIL / WIRE_PASSWORD 同策略废弃) —

单文件 SQLite(bun:sqlite,600):meta(版本/种子)+ session(单身份行)+ device_binding(一库一设备绑定)+ mls_clients/mls_convs/mls_seen(设备/群组映射/通知去重游标)+ idb_*(core-crypto IndexedDB 全量备份,进程启动时恢复、退出/关键步骤后落盘)。core-crypto 的 wasm 目标 只能用 IndexedDB(内存),SQLite 存的是它的快照+恢复,不是直连 keystore。

  • 一个库文件 = 一个身份:--session-file 切换即切换身份 + keystore + 游标(多身份并行互不干扰)。
  • 首次 login 自动注册本库设备(permanent、wire-cli label)+ PUT ed25519 公钥 + 上传钥包, 直接可用 mls one2one <uid> / mls create 发消息;同库重登复用已绑设备(校验服务端仍在, 不在则自动重建并提示)。新设备另开库文件(--session-file 指另一个 DB),删旧设备用 clients list 查看(删除走服务端 DELETE + 密码校验,cap 满 7 台时登录会交互询问删哪台)。
  • clients add / mls setup / --client 已移除:设备只在登录时自动产生,不再接受手工指定。
  • 旧 .json 会话文件已废弃:不做迁移、不读取,删掉后重新 login 即可。
  • 一个 keystore 只放一个设备:多设备请用不同库文件(否则 mlsInit 身份冲突导致签名/解析失败)。
  • client_id 绑定会轮换服务端 cookie:已捕获落盘,否则下一次刷新 403(bindToken 内处理)。
  • 首 commit 覆盖规则:须 Add 全部 MLS-capable client(create/one2one 会加全部认领到的钥包; 若自己有其他 stock 设备会直接 409 —— create/one2one 建组前有 preflight 检查并 abort,提示 burn 或换号)。
  • 钥包是“认领即消费”的:认领成功后 commit 若失败(409 等),认领到的包已烧掉,重试前需重新 top-up(join 自动补到 ≥2)。create/one2one 建组前有 preflight 检查自己其他 stock 设备(首 commit 须覆盖全部 MLS-capable client,含自己的其他设备;不满足直接 abort,提示 burn(找人认领掉)或换单设备号)。
  • mls restore 是新设备流程:全新 --session-file 登录(同账号会多一个设备)→ mls join --conv 入组 → 有新消息到达后再 mls restore。既有成员库跑 restore 会 0 readable(棘齿重放,预期内 FAIL,非 bug);seq 缺口只做 advisory(自己发出的行不进自己通知流,单端必有缺口);新成员解不开入组 epoch 之前的旧行(advisory)。restore 后如需发言走 mls send(发前自动同步 epoch,勿重复 join,否则 stale-epoch)。
  • mls recovery 是 P4 盲备份客户端:enable 发码(服务端只展示一次、存双 verifier 不存码)→ backup --conv ID --code C 本地 AES-256-GCM 封包(key=SHA256("wire-rs-recovery-v1:blob:"‖code))上传密文 → confirm --code C 抄写确认转 active;restore <真码> 即 fetch+本地开包取 conv 再走验链。unconfirmed 下重 enable 即轮换(旧码 403、待传 blob 被丢);active 下重 enable 直接 409。DELETE /recovery 恒 403(无回头路,销户级联清)。

--backend 与库内会话绑定地址不一致会直接报错(防串环境)。

register 只打印回包 profile(id/email/name/handle)与 zuid 到达情况,不写会话文件 (201 带 Set-Cookie: zuid 但无 access_token);login 才落盘(含 cookie=zuid,--verbose 可见刷新)。

目录结构

wire-cli/
  main.ts                 入口:全局 flag + 命令分发
  src/config.ts           会话读写
  src/http.ts             请求封装:Bearer + zuid cookie、错误输出
  src/format.ts           表格 / JSON 输出
  src/commands/login.ts
  src/commands/conversation.ts
  src/commands/events.ts  WebSocket 监控 + 轮询
  src/commands/client.ts      clients list(只读)+ registerDevice 内部 helper(login 自动注册 / demo 用)
  src/commands/mls.ts           mls create/one2one/join/send/recv/demo(持久化 MLS 收发 + 脚本演示)
  src/mls.ts                    core-crypto 最小封装 + IndexedDB 落盘(fake-indexeddb 垫片;node_modules 补丁见 patches/ 关闭 wasm 文件句柄,否则 bun 下退出码为 1)
  src/store.ts                  bun:sqlite 单库(session/keystore/游标/idb 快照,600,旧 .json 不读)
  src/commands/misc.ts        self/refresh/logout/notifications/health/register

后续规划

  • conversations create(POST /conversations;MLS 建组走 mls create)
  • 钥包认领即消费:失败的 commit 会烧包(已实现按需 top-up;后续可加用量预警)
  • events 落盘回放与按会话过滤
  • token 过期自动 refresh 重试