交付双端基础、实时联系人和隔离浏览器

This commit is contained in:
xhgit committed 2026-11-13 18:03:32 +08:00
1 parent 43687d5e7e
commit 67fef3ff87
59 files changed
+5094 -1

No files matched your search

+25
View File
@@ -0,0 +1,25 @@
# API 设计
所有业务接口使用 /api/v1,JSON 请求及响应。受保护接口通过 Authorization Bearer 接收短期会话令牌。错误结构为 `{"error":{"code":"…","message":"…"}}`。Web 与桌面端各自持有会话。服务端只保存令牌摘要。
| 方法 | 路径 | 请求与响应 |
|---|---|---|
| GET | /healthz、/readyz | 分别检查进程和 PostgreSQL、Redis |
| POST | /api/v1/auth/challenge | 返回 2 分钟单次使用的 challenge |
| POST | /api/v1/auth/register | 接收 username、password、deviceName、platform、publicKey、challenge、signature,返回 201 和 token、user、device |
| POST | /api/v1/auth/login | 同上,返回 200 |
| POST | /api/v1/auth/logout | 使当前会话失效,返回 204 |
| GET | /api/v1/me | 返回账号和当前设备 |
| GET | /api/v1/devices | 返回当前账号的设备列表,signedIn 表示有未过期会话,lastActiveAt 来自登录与 WebSocket 心跳 |
| DELETE | /api/v1/devices/{id} | 撤销指定设备和其全部会话,返回 204 |
| POST | /api/v1/realtime/ticket | 返回 30 秒单次 WebSocket 票据 |
| GET | /api/v1/realtime | 通过子协议 xhchat.v1 和 ticket.票据升级,服务器选择 xhchat.v1,连接建立后发送 ready 事件 |
| GET | /api/v1/contacts | 返回好友、来往申请和当前账号的黑名单 |
| GET | /api/v1/contacts/search?username= | 按完整用户名查找,返回可见的联系人状态 |
| POST | /api/v1/contacts/{id} | 请求体包含 action,可选 alias 和 category,成功返回 204 |
用户名为 3–32 位 ASCII 字母、数字或下划线,忽略大小写。密码最少 12 个 Unicode 字符,最多 256 字节。platform 为 web 或 windows。公钥、签名和 challenge 使用无填充 Base64URL。设备使用 Ed25519 签名 UTF-8 字符串 `XHChat device authentication v1\n` 后紧接 challenge。该签名仅用于证明基础设备密钥持有权。
联系人操作包含 request、accept、reject、cancel、delete、block、unblock 和 preferences。变更后 WebSocket 发送 contacts_changed,客户端重新获取授权后的列表。
下一阶段接口为 /conversations、/conversations/{id}/envelopes、/sync、/attachments、/key-packages。消息接口接受版本化协议密文、目标会话和幂等 ID。WebSocket 发出同步提示,客户端按持久游标补拉。后续加入 /groups、/calls、/posts、/backups、/push 与独立的管理接口。
+30
View File
@@ -0,0 +1,30 @@
# XHChat 技术可行性与总体架构
Windows 和 Web 可共用 Vue 3、TypeScript、Pinia 和 Vue Router。Go 服务以模块化单体起步,按身份、设备、联系人、投递、群组、文件、信令、动态与管理划定接口。PostgreSQL 保存权威状态,Redis 负责限流、短期票据和实时事件分发,S3 兼容存储承载附件密文。服务按部署量拆分时保持相同的 REST 和 WebSocket 契约。桌面端使用随包发布的受信任应用资源,网页通过 Nginx 与 API 同源部署。Android、iOS 和其他桌面系统使用同一协议,各自实现平台密钥存储。
功能交付按需求的八阶段推进。阶段一优先闭环用户名注册、密码登录、独立设备身份、设备列表与撤销、WebSocket 会话及容器部署。阶段二到三交付加密私聊、附件、离线投递、加密群组、可信设备授权和备份。阶段四交付 WebRTC、TURN、SFU 与媒体 E2EE。阶段五交付内置浏览器。阶段六到八交付社交、扩展生态、独立管理后台完善、发布与运维。短信、邮件、支付和推送使用各部署方的凭据,验收使用实际接通的服务。
端到端加密的可行性取决于同一协议库在浏览器和桌面的兼容性,以及设备认证、密钥持久化和撤销的集成验证。音视频需要验证目标浏览器的编码帧变换支持及跨网络 TURN 转发。普通网页浏览与通讯端的密钥和会话数据使用不同 Electron 会话。网页客户端通过系统浏览器打开第三方链接。
## 目录设计
```text
XHChat/
Desktop/ Electron 主进程、preload、打包、独立浏览器
web/ Vue 客户端与可打包的渲染层
Android/ 后续 Android 客户端
server/
cmd/api/ API 入口
internal/config/ 环境配置
internal/account/ 账号、会话、设备身份
internal/httpapi/ HTTP 和 WebSocket 边界
internal/database/ 迁移与连接
internal/{contacts,delivery,groups,files,calls,social,admin}/ 后续模块
admin/ 独立管理前端
deploy/ Nginx、TLS、TURN、SFU、备份恢复
tests/ 双端集成、隔离和验收脚本
docs/ API、数据库、安全设计与验收记录
docker-compose.yml
```
管理端计划使用独立域名、凭据和数据库角色。指标聚合使用投递计数、调用状态和基础设施容量。管理角色只需接触运营元数据。
+11
View File
@@ -0,0 +1,11 @@
# 浏览器安全架构
受信任的聊天与浏览器工具栏从随包静态资源加载。第三方网页进入独立 WebContentsView 和单独 Session,禁用 Node、preload 与 webview,启用 sandbox、contextIsolation、webSecurity。普通与隐私模式使用不同分区,隐私窗口销毁后清理其临时分区。主进程校验 IPC 的 WebContents、主帧、来源和参数。应用自定义协议只注册到受信任会话,资源查找使用固定目录和可访问资源边界。 [Electron 安全指南](https://www.electronjs.org/docs/latest/tutorial/security) · [Electron Web 嵌入](https://www.electronjs.org/docs/latest/tutorial/web-embeds/)
内置浏览器将以 Chromium 的真实 UA 追加 XHChat/版本,保留 UA-CH 默认协商并用测试站检查一致性。导航、重定向和新窗口只接受允许的网络协议。摄像头、麦克风、剪贴板、通知与位置默认拒绝,后续按可信 UI 中的顶级网站授权。下载由可信 UI 确认路径及来源。恶意站点警告机制需要评估信誉服务、误报与隐私影响。
聊天链接卡片由发送者主动请求预览。若采用代理,部署独立网络出口并在每次重定向及实际建连时校验公网目的地址,限制响应类型、体积、超时与跳转次数。代理只接收明确提交的 URL,卡片由客户端随 E2EE 消息传输。安全验收包含远程网页的权限拒绝、无特权对象、无通讯存储可见性和自定义协议隔离。
## 威胁模型
攻击者包括被动窃听者、恶意联系人、被撤销设备、第三方网页、服务端入侵者和能修改 Web 发布内容的操作者。服务端可见投递及账号元数据,不能解密内容。服务端若能操纵设备目录,端侧必须通过可信设备授权与可验证身份限制密钥替换。受控发布、签名安装包、依赖锁定、CSP 与最小权限用于降低执行恶意代码的风险。设备已解锁且被完全控制时,应用不能保护当前可解密内容。
+17
View File
@@ -0,0 +1,17 @@
# 数据库设计
| 关系 | 关键约束与职责 |
|---|---|
| users | UUID 主键,规范化用户名唯一,密码保存 Argon2id PHC,记录创建时间 |
| devices | UUID 主键,用户外键,用户内公钥唯一,记录平台、首次和最近活动时间、撤销时间 |
| sessions | 高熵令牌的 SHA-256 摘要为主键,关联设备,包含到期时间 |
| contact_relationships、contact_blocks、contact_preferences | 关系按账号对去重,拉黑有方向,私有备注按拥有者授权 |
| conversations、memberships | 会话与成员关系,记录角色和生效世代 |
| device_credentials、key_packages | 公开凭据及一次性密钥包,事务领取,撤销后停止发放 |
| envelopes、deliveries | 二进制协议密文、投递游标和目标设备,按客户端消息 ID 幂等 |
| attachments、backups | 对象存储标识、密文尺寸、配额和版本,密钥由端侧传递 |
| calls、call_participants | 通话状态、参与设备和时间,不存媒体 |
| posts、post_audiences、reactions | 私人动态正文为密文,受众变更触发重新分发或换钥 |
| admin_audit | 管理员、行为、目标标识、时间和结果 |
迁移 001 创建身份相关表。迁移 002 添加联系人关系、黑名单和备注。设备撤销和会话清除在同一个事务内处理。阶段二以事务分配单调投递游标,连接恢复后从持久层补拉。消息保留和附件清理分别由后台作业处理,下载授权按目标设备和对象关联重新检查。
+9
View File
@@ -0,0 +1,9 @@
# 部署与维护
当前 Compose 启动 Nginx、Go API、PostgreSQL 和 Redis。PostgreSQL 与 Redis 仅供 Compose 网络使用。Nginx 的端口默认绑定本机。所有服务健康后,通过 /readyz 验证数据库与缓存。
使用自定义域名时,将 XHCHAT_WEB_ORIGIN 设置为实际的 HTTPS 源,使用 TLS 反向代理转发到 127.0.0.1 上的 Compose 端口。反向代理应转发 Host、WebSocket Upgrade 与 Connection,配置证书续期和 HSTS。桌面端的 XHCHAT_SERVER_URL 指向同一 HTTPS 源。应用凭据及数据库连接信息由部署方提供。数据库密码使用十六进制字符串,避免连接 URL 的保留字符。正式环境需要数据库角色分离、备份演练、容量与限流调优。
使用 `docker compose logs api` 检查应用日志。停止服务用 `docker compose down`。PostgreSQL 的数据由 Compose 命名卷保存。
使用 `pg_dump` 生成数据库备份,备份包含账号与设备元数据,应在受控环境加密保存。使用 `pg_restore` 恢复到独立数据库,执行迁移与 API 验证后切换服务。恢复时清除历史会话并重建 Redis 短期状态。阶段一暂无聊天和附件数据。
+9
View File
@@ -0,0 +1,9 @@
# 加密架构
优先验证 RFC 9420 MLS。私聊以两个账号的可信设备组成会话,群聊采用同一协议。每台设备单独作为成员加入,安全码和二维码验证绑定账号信任根。X3DH / PQXDH、Double Ratchet 与 Sesame 是 Signal 私聊和多设备的候选组合。官方 libsignal 提供原生及 Node.js 等绑定,采用 AGPL,Web 构建及分发模式需要额外评估。OpenMLS 采用 MIT,公开 CI 将 WASM 列为构建但未测试的平台。mls-rs 支持 RFC 9420,公开文档将 Web Crypto 提供者标为实验性并说明尚无完整第三方安全审计。实现暂未定版。 [Signal 规范](https://signal.org/docs/) · [libsignal](https://github.com/signalapp/libsignal) · [MLS 协议](https://datatracker.ietf.org/doc/html/rfc9420) · [MLS 架构](https://datatracker.ietf.org/doc/html/rfc9750) · [OpenMLS](https://github.com/openmls/openmls) · [mls-rs](https://github.com/awslabs/mls-rs)
基础设备密钥使用 Ed25519 及标准库。Web 用不可导出的 CryptoKey 持久化到 IndexedDB,桌面用系统安全存储加密私钥。阶段一账号登录创建的设备身份仅用于服务认证。加入 E2EE 会话还需要既有可信设备授权或显式重建信任。服务端只保存公钥。账号找回不能重建聊天密钥。设备撤销必须同时取消投递权限与 MLS 成员资格,客户端完成新世代提交后才可发送。新成员默认只能读取加入后的内容。
协议选型验收包括固定版本与依赖、公开审计覆盖、RFC 向量、独立实现互通、离线 Commit 重放、并发世代、恶意服务端替换密钥、存储中断与恢复、已撤销设备不能解密新内容。客户端需要原子提交协议状态与待发送密文,避免重试时复用发送状态。前向保密与入侵后恢复取决于 MLS 世代更新、旧秘密清除和对手退出设备。
附件采用公开的分块认证加密格式,评估带明确结束认证与大文件恢复语义的实现。每份附件生成独立随机密钥,密文通过对象存储分发,文件密钥及完整性元数据放在 E2EE 消息中。备份使用独立随机恢复秘密,显式确认恢复权限和完整性,服务端只存密文及版本。私人动态按受众分发密钥。Web 应用以同源、受控发布和严格 CSP 管理脚本信任,当前页面的恶意同源脚本属于独立威胁。
+30
View File
@@ -0,0 +1,30 @@
# 开发与验收记录
## 2026-11-13 · 阶段一基础交付
Web 和 Electron 共用 Vue 客户端,独立接入同一 Go API。真实 PostgreSQL 迁移创建账号、设备和会话表。Redis 用于限流、单次设备验证挑战和 WebSocket 票据。Windows 使用 Electron safeStorage 持久化设备私钥。Web 使用 IndexedDB 中的不可导出 Ed25519 CryptoKey。会话令牌只保存在客户端进程内存中,刷新网页或重启应用需要重新登录。
| 验收项 | 结果 |
|---|---|
| Go 单元测试 | 覆盖 Ed25519 签名、挑战绑定、Argon2id 密码验证与盐值 |
| Web、Electron 构建 | Vue 与 TypeScript 构建通过 |
| Compose 启动 | Nginx、Go API、PostgreSQL、Redis 健康检查通过 |
| 真实 API 集成 | 覆盖注册、重复用户名、错误密码、登录、设备状态、跨账号撤销拒绝、来源校验、挑战与票据重放拒绝、退出和撤销 |
| Edge 与 Electron 交叉测试 | Web 注册后用 Windows 登录,从 Web 撤销 Windows 设备,实时会话结束并返回登录页 |
| 端侧检查 | Web 私钥不可导出,Electron 渲染层没有 Node require,390px Web 设备页无横向溢出 |
| 依赖扫描 | Go 1.27.1 升级至 1.27.4 后,govulncheck 未报告漏洞。npm audit 未报告漏洞 |
两套集成测试使用随机账号和随机密码。测试账号留在本机开发数据库中,复跑时使用新账号。
## 尚待实现
- 阶段一还需邮箱和手机号注册、验证码服务、找回密码和双重验证。真实联调需要 SMTP 与短信供应商配置。
- 阶段二与三还需定版并验证双端 E2EE,交付私聊、附件、离线消息、群聊、多设备可信授权、加密备份与同步。当前基础设备认证没有消息密钥能力。
- 阶段四还需 WebRTC 音视频、TURN、SFU、屏幕共享及媒体 E2EE。
- 阶段五还需持久书签和历史、下载记录、逐站授权、反钓鱼及聊天联动。
- 阶段六到八还需社交、扩展生态、独立管理后台、推送、生产部署与备份演练、压力测试、安全评估、签名安装包和发布流程。
## 联系人和 Chromium 浏览器
- 双端支持用户名查找、申请、接受、拒绝、撤回申请、备注、分组、删除、拉黑和解除拉黑。测试以 Web 与 Electron 两个账号验证申请和变更实时同步。
- 桌面端提供隔离浏览器窗口,支持地址栏、搜索、标签、导航、缩放、全屏、复制链接、普通窗口下载、隐私窗口和清除站点数据。集成测试确认远程网页位于独立 Session,Sandbox 生效,网页无 IPC 桥和 Node require,UA 保留真实 Chromium 版本并追加 XHChat 标识。测试同时验证地址栏拒绝本地文件协议。
+7
View File
@@ -0,0 +1,7 @@
# 音视频架构
信令经 Go API 和 WebSocket 传输,按参与设备授权。通话状态机处理邀请、响铃、接听、拒绝、占线、重连和结束。邀请及 SDP 指纹应由已验证的设备绑定至 E2EE 会话,ICE 及信令日志只记录必要状态。
一对一使用 WebRTC 和 ICE,直连失败时通过 coturn 转发。TURN 凭据短期有效,并配置目的地址限制、带宽配额和公开中继端口。多人通话选型优先验证 LiveKit SFU 与其 Web SDK 的媒体 E2EE,核查固定版本、许可证、加密实现及浏览器支持。通过 RFC 9605 SFrame 或通过评估的等效实现保护音频、视频和屏幕共享。密钥由端侧授权会话提供,加入、退出或撤销时轮换。客户端在加密能力缺失或变换失败时停止发布媒体。TURN 转发数据和 SFU 可观察的网络元数据纳入威胁模型。 [coturn](https://github.com/coturn/coturn) · [SFrame RFC](https://www.rfc-editor.org/info/rfc9605/) · [LiveKit 加密](https://docs.livekit.io/transport/encryption/)
验收覆盖 Windows↔Web 两个发起方向、直连和强制 TURN、多人加入与移除、媒体权限拒绝、屏幕共享、切网恢复、SFU 无法解密及不支持环境阻止发布。