授权指令包

授权指令包（Authorization Packet）是一种安全的指令委托机制，允许有权限的用户将某个操作委托给他人执行。

应用场景

授权指令包解决的核心问题：委托者不在场，但操作需要在设备附近执行。

场景	说明
添加新用户	房东远程授权，租客到门锁前自行激活账户
录入生物凭证	管理员授权，用户本人到锁前录入指纹/人脸
临时开锁	授权访客一次性开门，无需分享自己的凭证

适用于纯蓝牙设备

WiFi 设备可通过云端直接下发指令。授权指令包主要用于无网络连接的蓝牙设备场景，或需要端到端安全的场景。

工作原理

授权包结构

授权指令包采用 JWT（JSON Web Token）格式，使用委托者的 userSecret 进行 HMAC-SHA256 签名。

JWT Header

json

{
  "alg": "HS256",
  "typ": "JWT"
}

JWT Payload

字段	类型	必填	说明
iss	uint32	是	签发者用户ID（委托者）
iat	uint64	是	签发时间（UNIX秒时间戳）
exp	uint64	是	过期时间（UNIX秒时间戳）
jti	string	是	唯一标识（nonce），防重放
dev	string	是	目标设备序列号
cmd	bytes	是	加密的指令数据（Base64编码）

指令数据加密

cmd 字段包含的指令数据使用委托者的 userSecret 加密（AES-128-CBC），执行者无法解密查看具体内容。设备端使用相同密钥解密后执行。

Payload 示例

json

{
  "iss": 1,
  "iat": 1710000000,
  "exp": 1710086400,
  "jti": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "dev": "SN123456789",
  "cmd": "Base64EncodedEncryptedCommandData..."
}

签名

使用委托者的 userSecret 作为密钥，对 header.payload 进行 HMAC-SHA256 签名：

signature = HMAC-SHA256(base64(header) + "." + base64(payload), userSecret)

最终授权包格式：

base64(header).base64(payload).base64(signature)

执行流程

提交授权包

执行者连接设备后，通过 SubmitAuthPacket 指令提交授权包。

指令码	指令名	方向	鉴权
`0x0010`	SubmitAuthPacket	APP → 设备	无需鉴权

请求参数

字段	类型	必填	说明
packet	string	是	JWT 格式的授权指令包

请求示例

json

{
  "packet": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOjEsImlhdCI6MTcxMDAwMDAwMCwiZXhwIjoxNzEwMDg2NDAwLCJqdGkiOiJhMWIyYzNkNC1lNWY2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAiLCJkZXYiOiJTTjEyMzQ1Njc4OSIsImNtZCI6IkJhc2U2NEVuY29kZWRFbmNyeXB0ZWRDb21tYW5kRGF0YS4uLiJ9.signature"
}

响应参数

字段	类型	必填	说明
code	uint32	是	状态码，0=成功
result	object	否	指令执行结果（成功时返回）

响应中的 result 内容取决于授权包内的具体指令。例如，若为 AddUser 指令，则返回：

json

{
  "code": 0,
  "result": {
    "userId": 2,
    "userSecret": "a1b2c3d4e5f6..."
  }
}

设备端处理流程

传递方式

授权指令包支持多种传递方式，适用于不同的业务架构：

方式	适用场景	说明
二维码	面对面、离线场景	委托者生成二维码，执行者扫码获取
链接分享	微信/短信分享	授权包作为 URL 参数传递
云端中转	有服务器架构	上传到服务端，执行者从云端拉取
MQTT消息	IoT 架构	通过 MQTT broker 传递
本地存储	离线 APP	导出文件，执行者导入

支持委托的指令

以下指令支持通过授权指令包委托执行：

指令码	指令名	典型场景
`0x0201`	AddUser	远程授权新用户激活
-	AddCredential	授权他人录入生物凭证
-	Unlock	临时访客一次性开门

扩展性

协议设计上，任何需要"委托他人在设备附近执行"的指令都可以封装为授权指令包。具体支持列表由设备固件决定。

安全机制

机制	说明
JWT 签名	防篡改，设备验证委托者身份
指令加密	执行者无法查看具体操作内容
Nonce 防重放	每个授权包只能使用一次
有效期	过期自动失效，限制时间窗口
设备绑定	授权包与目标设备绑定，无法用于其他设备
权限继承	设备检查委托者是否有权执行该指令

安全建议

授权包有效期建议设置为 24-72 小时
敏感操作（如添加管理员）建议缩短有效期
APP 应在授权包使用后提示委托者

错误码

错误码	说明
0	成功
1001	授权包格式无效
1002	签发者用户不存在
1003	签名验证失败
1004	授权包已过期
1005	授权包已使用（nonce 重复）
1006	目标设备不匹配
1007	签发者权限不足
1008	指令解密失败

授权指令包 ​

应用场景 ​

工作原理 ​

授权包结构 ​

JWT Header ​

JWT Payload ​

Payload 示例 ​

签名 ​

执行流程 ​

提交授权包 ​

请求参数 ​

请求示例 ​

响应参数 ​

设备端处理流程 ​

传递方式 ​

支持委托的指令 ​

安全机制 ​

错误码 ​

授权指令包

应用场景

工作原理

授权包结构

JWT Header

JWT Payload

Payload 示例

签名

执行流程

提交授权包

请求参数

请求示例

响应参数

设备端处理流程

传递方式

支持委托的指令

安全机制

错误码