底座无认领码配网 HTTPS 契约

状态:已确认的目标软件契约,当前后端代码尚未实现,仍待硬件团队同步及真机联调。本文不代表甲方冻结或已完成联调。

配套文件:HTTP OpenAPI、MQTT AsyncAPI。

1. 信任边界与流程

  1. 受控装配/导入流程在平台登记 deviceId=SN 和设备类型 base;出厂底座烧录全产品共用的固定 bootstrap password,不在产线预置每设备独立的 mqttToken。
  2. 用户长按实体底座进入配网窗口。底座 Write Characteristic 在 GATT 权限层要求 LE 加密;App 完成配对并读取完整 SN。
  3. 已登录 App 为该 SN 创建 5 分钟一次性会话。账号只来自服务端登录态。
  4. App 通过加密 BLE 0x53 写入 Wi-Fi、sessionId、token 和到期时间;底座锁定当前实体窗口首个合法会话。
  5. 底座联网后,以 Authorization: Device <credential> 调用 HTTPS 确认接口,并在 JSON 中提交 SN 和一次性会话凭证。首次激活时 credential 为固定 bootstrap password;已经生成一机一密的设备除原已完成会话的幂等重试外,只能使用当前 mqttToken。
  6. 云端校验设备凭据、会话、时效和归属冲突。首次激活成功时生成 32 随机字节的 mqttToken,并在同一事务中写入设备配置、建立账号归属和完成会话。
  7. 成功响应向设备返回 {deviceId, mqttToken}。底座必须安全持久化 mqttToken,随后以 clientId=username=SN、password=mqttToken 连接 MQTT/TLS;固定 bootstrap password 不得用于 MQTT。
  8. 原会话有效期内以相同请求重试时,云端必须返回已经生成的同一个 mqttToken,不得再次生成或覆盖一机一密。
  9. App 查询会话,只有 completed 才显示成功;App 查询接口不返回 mqttToken,BLE ACK、Wi-Fi connected 和 MQTT online 都不能替代该状态。

所有生产 HTTP 链路必须使用 HTTPS 并校验服务端证书。固定 bootstrap password 只能作为首次激活的出厂凭据,sessionId 和一次性 token 证明本次近场配网;任一条件缺失均不得生成一机一密。已生成 mqttToken 的设备必须拒绝再次使用固定 password 激活;唯一例外是原已完成会话在有效期内取回同一 mqttToken 的幂等重试。固定 password 实际值、一次性 token 和 mqttToken 均不得进入普通日志、trace 或错误响应,App 不获取任何设备长期凭据。

2. API

测试环境 Host 为 rooive.weavemeta.cn。

外网网关统一增加 /api 前缀。App 接口使用 Authorization: Bearer <consumer access token>;设备确认使用大小写固定的 Authorization: Device <credential>。首次激活的 credential 为固定 bootstrap password,后续设备确认使用当前 mqttToken。JSON Content-Type 为 application/json。

平台成功响应统一为 {"message":"success","result":{...},"status":200,"timestamp":...};以下示例只展示 result。

创建会话

POST /consumer/devices/provisioning-sessions

{"deviceId":"BSN202607240001","alias":"Home base"}

成功 result:

{
  "sessionId":"00112233445566778899aabbccddeeff",
  "deviceId":"BSN202607240001",
  "token":"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
  "expiresAt":1790000300000,
  "status":"pending"
}

sessionId 是 16 随机字节的小写 HEX,token 是 32 随机字节的小写 HEX;有效期固定 300000ms。服务端只保存一次性 token 哈希。不同账号可以创建候选 pending,最终只有同时持有合法设备凭据并收到 BLE 会话的底座可以确认,避免只知道 SN 即抢绑。

查询和取消

GET|DELETE /consumer/devices/provisioning-sessions/{sessionId} 仅允许创建账号访问。查询返回 {sessionId, deviceId, expiresAt, status},其中 status 为 pending | completed | expired | cancelled,不回传 token、固定 password 或 mqttToken。取消只影响 pending,不用于解绑已归属设备。

设备确认

POST /consumer/device-provisioning/_confirm

Authorization: Device <credential>
Content-Type: application/json
{
  "deviceId":"BSN202607240001",
  "sessionId":"00112233445566778899aabbccddeeff",
  "token":"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f"
}

首次激活成功响应 result 为:

{
  "deviceId":"BSN202607240001",
  "mqttToken":"43位无填充Base64URL设备独立凭据"
}

固定 bootstrap password 由出厂烧录,仅用于尚未生成一机一密的设备完成首次 HTTPS 激活,不得写入本文或其他仓库文件。mqttToken 由后端在首次激活时使用 32 随机字节生成,编码为 43 位无填充 Base64URL 文本,并原子写入平台设备配置。底座收到后必须安全持久化,并用它连接 MQTT/TLS。已激活设备的新确认请求只允许当前 mqttToken;固定 password 仅可在下述原会话幂等重试中使用。

同一 sessionId、deviceId 和 token 在原 expiresAt 前重试时,设备可继续携带首次请求使用的固定 bootstrap password,响应必须返回首次成功时的同一个 mqttToken。该例外仅用于处理成功响应丢失,不得重新生成凭据、重复归属或用于任何新会话。

3. 重试、归属与错误

HTTP 消息标识 含义
400 consumer.provisioning.invalid_request SN 或其他请求参数不合法。
400 consumer.provisioning.base_required 设备不是允许配网的底座。
403 consumer.provisioning.invalid_proof SN、一次性 token、固定 password 或设备 mqttToken 不匹配,不指出具体错误项。
404 consumer.provisioning.not_found 会话或设备不存在。
409 consumer.device.already_bound 设备已有归属。
409 consumer.device.limit_exceeded 账号设备数量达到限制。
409 consumer.provisioning.cancelled 会话已取消或失效。
410 consumer.provisioning.expired 会话已过期。
503 consumer.provisioning.credentials_missing 服务端未配置首次激活能力,或无法生成、保存设备独立 mqttToken。

4. 需要硬件同步的事项

  1. GATT Write Characteristic 强制加密,未加密时不得接受 Wi-Fi 或会话凭证。
  2. 实现 AP 扫描分片 0x52、带会话的 0x53、回显 command_id 的 0xD3 和 Wi-Fi 状态 0x54。
  3. 用户长按底座开始配网后,底座只接受本次收到的第一组有效会话信息,之后其他手机不能覆盖。再次长按只能重新开始本地配网,不能解除或更换设备在云端已绑定的账号。
  4. 产线为底座写入 SN 和固定 bootstrap password;固定 password 仅允许用于 HTTPS 首次激活,不得用于 MQTT,也不得通过 App、BLE、日志或错误响应泄露。
  5. Wi-Fi connected 后调用上述 HTTPS 接口,首次激活使用固定 password;收到 mqttToken 后必须安全持久化,并立即切换为一机一密。
  6. 固件对原会话重试必须使用原请求并接受、保存相同 mqttToken,不得因响应丢失触发新的凭据生成;除该幂等重试外,已激活设备不得回退使用固定 password。
  7. App 以云端 completed 为最终成功。本次不包含家庭模型和项圈 Pogo 自动激活。