一代机激活 API

一代机 V1.6 兼容老云激活协议。该 API 仅服务 DYJ gen1 onboarding，和 /device/* 的 Device Token 鉴权隔离。

基础信息

• 基础路径：/api/auth
• 响应封套：{ "success": boolean, "code": string, "message": string, "data": object | null }
• 激活码：8 位大写字母/数字，5 分钟有效，一次性兑换。
• JWT：exchange 返回 HS256 Bearer JWT，payload 兼容老云 { deviceId, deviceName }。

端点

POST /api/auth/generate

按 deviceId 生成一次性激活码。

请求

{ "deviceId": "DYJ-GEN1-001" }

响应

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "data": { "authCode": "A1B2C3D4", "expiresIn": 300 }
}

POST /api/auth/exchange

设备用激活码换取 legacy Bearer JWT。expiresIn: 0 表示按老云契约签发无过期时间 token。

请求

{
  "authCode": "A1B2C3D4",
  "deviceId": "DYJ-GEN1-001",
  "deviceName": "客厅点一机",
  "deviceModel": "DYJ_V1",
  "expiresIn": 0
}

响应

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "data": {
    "accessToken": "<jwt>",
    "expiresIn": 0,
    "deviceId": "DYJ-GEN1-001"
  }
}

GET /api/auth/info

使用 Authorization: Bearer <jwt> 查询设备激活信息。

响应

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "data": {
    "deviceId": "DYJ-GEN1-001",
    "name": "客厅点一机",
    "model": "点一机·一代",
    "status": "online",
    "lastOnlineTime": "2026-06-14T01:29:00.000Z"
  }
}

安全边界

• generate / exchange 只接受 hw_inventory.hardware_id 命中且产品型号为 generation='gen1'、status='active' 的库存设备。
• 接口按 IP 和 deviceId 双维度限流，并写入激活审计表。
• legacy JWT 只挂在 /api/auth/info 与未来 gen1 legacy 端点，不授予 /device/heartbeat、/device/acme 等 Device Token 能力。

已知风险

该协议为兼容老云，generate 无设备持有证明；知道有效 gen1 hardware_id 的调用方理论上可以发起激活流程。当前缓解为库存门禁、限流、审计和 JWT 作用域隔离。后续平台加固应在设备可发版时引入设备持有证明或 nonce challenge。

• 限流为单进程内存态：后端横向扩容（多实例）时各实例独立计数，同一 IP/设备的实际限额会被放大到约 N 倍。一代机激活为低频 onboarding 流量，当前可接受；上量后需改为共享存储（Redis 等）。
• 审计表保留策略（issue #755 已落地）：hw_device_activation_audit_logs 会随调用持续增长。已接入 pg_cron 任务 archive-hw-activation-audit-logs（每日 01:37 调 POST /cron/archive-hw-activation-audit-logs），把超过 90 天的记录搬入归档表 hw_device_activation_audit_logs_archive 永久保留，热表保持精简。归档幂等，全量数据两表合并可查。