设备授权 devices

面向桌面工作台与 magic-stack CLI 的设备授权接口。

Token 模型

Token	有效期	用途
access JWT	24h	含 device/scope:"magic-stack" claim，CLI 凭此放行
refresh token	90d	opaque 字符串，服务端只存 SHA-256，明文仅返回一次

---

POST /api/devices/register

注册（或更新）本机设备，领取 access token + refresh token。

按 (userId, 设备指纹) upsert 设备记录。同一设备多次注册不会重复创建， 只会刷新 token。

鉴权：需 Authorization: Bearer <JWT>（用户登录态）

请求体（JSON）

字段	类型	说明
fingerprint	string	设备指纹（sha256(device_uuid)）
name	string	设备名称（如主机名）

响应 200

{
  "accessToken": "<JWT, 24h>",
  "refreshToken": "<opaque, 90d>",
  "expiresIn": 86400
}

---

GET /api/devices

列出当前用户已注册的所有设备。

鉴权：需 Authorization: Bearer <JWT>

响应 200

{
  "devices": [
    { "id": "...", "name": "...", "fingerprint": "...", "revokedAt": null, "lastSeen": "..." }
  ]
}

---

DELETE /api/devices/:id

主动吊销某台设备（自助管理）。

鉴权：需 Authorization: Bearer <JWT>（只能吊销本账号的设备）

响应 200

{ "ok": true }

---

POST /api/cli/refresh

用 refresh token 续期，不走 JWT 鉴权。轮换返回新的 access token + refresh token（旧 refresh token 作废）。

限流：60 秒内同 IP 最多 30 次。

请求体（JSON）

字段	类型	说明
refresh_token	string	当前有效的 refresh token

响应 200

{
  "access_token": "<JWT, 24h>",
  "refresh_token": "<新 opaque token, 90d>",
  "expires_in": 86400
}

重用检测：旧 token 在 60s 宽限窗外再次出现 → 判定为 token 泄露，自动吊销设备， 返回 401 device_revoked。

账号停用：若账号 dev_enabled=false，返回 403 dev_disabled。

错误码含义见 错误码。