Add authenticated WiFi transport with BLE fallback

2026-10-01 14:32:18 +08:00
parent 071f06d365
commit f011d8357d
55 changed files with 6327 additions and 29 deletions
@@ -1,5 +1,15 @@
 # 奇妙小屏幕 BLE 控制协议 1.0

+## WiFi 通道扩展 1.2
+
+能力 wifi_transport。加密 BLE transport.offer 返回 channel_id（16 随机字节小写 hex）、secret（32 随机字节 Base64）、device_id、host（当前 WiFi IPv4）、port=8080、path=/ws/mobile、expires_in_ms=10000。每次 offer 撤销前一候选；活动通道须先 close。BLE transport.close 在串行门禁内撤销候选与活动通道，作为回退执行屏障。session.*、wifi.*、task.get 与通道协商只走 BLE。
+
+KDF：T=SHA256(ASCII(channel_id))；HKDF-SHA256(secret,salt=T,info=ASCII("QMS-WIFI-1")||T,length=72)。密钥及 nonce prefix 布局沿用 BLE Cipher，AAD 标签为 QMS-WIFI-1；双向序号独立从 0 开始，不共享 BLE 计数。最大加密记录 65536 字节。
+
+WebSocket 首个二进制消息为 ASCII(channel_id) 的 32 字节加加密 JSON {device_id}，5 秒内送达；设备验证凭据、BLE 会话及身份后一次消费，返回加密 {device_id,ready:true}。之后每条二进制消息为加密 RPC JSON，格式沿用原协议；WiFi 请求编号独立递增。transport.ping 是 WiFi 唯一通道级方法，每 5 秒调用、5 秒超时，不延长 BLE 活跃时间。设备 10 秒无有效 WiFi 消息撤销通道。
+
+会话锁串行业务和撤销；BLE 断开使 WiFi 失效。只读失败回退后可重取；写入结果不明不重放，回读并提示。旧凭据、错误身份、篡改、重放、非二进制、超长消息拒绝；凭据不进 URL/日志/磁盘。未认证连接不得踢掉合法通道。WiFi 建立不增加 mobile.generation；mobile.active_transport 为 ble/wifi/null。
+
 本文是首版实现契约。Python／Kotlin 加密黄金向量、分片和 Android 13 真实 BLE 已有通过记录；各业务验收范围见测试结果归档，不能据此推断所有场景通过。命令只能进入设备公共业务服务，不调用网页 DOM，不提供 shell、任意路径或原生驱动地址。变化登记到跨端兼容记录。

 ## 1. GATT 与广播
@@ -91,3 +101,5 @@ BLE 只接收白名单方法。旧客户端遇新能力忽略；旧设备缺某
 ## 2026-09-26 兼容扩展
 library.list 的用户条目遵循设备持久混合顺序，顺序变化影响 library_revision 和游标。演示条目固定在用户条目之前。
 task.get 可附加脱敏 error_code（AUTH_FAILED、NETWORK_UNAVAILABLE、IP_CONFIG_FAILED、UNKNOWN）；旧客户端可忽略。没有可靠原因时用 UNKNOWN。wifi.get 仍不含密码。协议主版本保持 1。
+
+兼容说明：原 mobile.transport 为 BLE 统计对象，保持原义；实际链路新增 active_transport，不改变旧字段类型。