魔盾验证 开发文档

快速开始

所有 HTTP 接口使用 JSON，基础地址为你的 魔盾验证 服务地址，例如 https://auth.example.com。客户端流程通常是：注册设备 → 兑换卡密 → 拉配置 → 定时心跳。

# 1. 注册设备，拿到 device_token
curl -X POST https://auth.example.com/v1/client/device/register \
  -H 'Content-Type: application/json' \
  -d '{"app_id":"app_xxx","device_pub":"...","fingerprint":{"composite":"..."},"sdk":{"os":"windows","arch":"amd64","name":"PC"}}'

# 2. 用卡密兑换授权
curl -X POST https://auth.example.com/v1/client/card/redeem \
  -H 'Authorization: Bearer dt_xxx' \
  -H 'Content-Type: application/json' \
  -d '{"card_key":"AEGSXXXX...","device_id":"dev_xxx"}'

认证方式

卡密兑换、心跳、配置、试用需要设备或终端用户 token。设备 token 有效期一年，服务端可随时吊销。

设备注册

POST /v1/client/device/register

设备公钥必须是 32 字节 X25519 公钥的 base64url 编码。指纹建议使用稳定的机器码组合，服务端只保存 SHA-256。

{
  "app_id": "app_xxx",
  "device_pub": "base64url-32-bytes",
  "fingerprint": {"composite": "machine-code"},
  "sdk": {"os": "windows", "arch": "amd64", "name": "办公室电脑", "device_type": "desktop"}
}

{
  "code": 0,
  "data": {
    "device_id": "dev_xxx",
    "device_token": "dt_xxx",
    "policy": {"max_devices": 1},
    "server_time": 1793860000000
  }
}

卡密兑换

POST /v1/client/card/redeem

{"card_key":"AEGS7K2M9XQ4B3TN8W5H","device_id":"dev_xxx"}

卡密不区分大小写，可带可不带分隔符。成功后会创建或续期授权，并绑定当前设备。卡密激活会自动生成终端用户，用户名就是卡密。

{"code":0,"data":{"license":{"id":"lic_xxx","status":"active","expires_at":"..."},"bound_device_id":"dev_xxx","server_time":1793860000000}}

拉取配置

GET /v1/client/config

返回公告、卡密类型、客户端策略、版本更新信息。客户端应在启动和心跳时检查 config_version。

{
  "code": 0,
  "data": {
    "app_id": "app_xxx",
    "config_version": 9,
    "notice": {"enabled": true, "title": "公告", "content": "..."},
    "update": {"version": "1.2.0", "download_url": "https://...", "content": "...", "force": true},
    "policy": {"max_devices":1,"allow_rebind":true,"rebind_cost_hours":24,"heartbeat_interval_s":30,"trial_hours":2,"allow_register":true,"offline_after_s":90,"anti_debug":false,"anti_vm":false,"anti_emulator":false}
  }
}

领取试用

POST /v1/client/trial

需要设备 token。每台设备只能领取一次，时长由软件设置里的 trial_hours 决定。

{"code":0,"data":{"license":{"id":"lic_xxx","status":"active","expires_at":"..."},"server_time":1793860000000}}

心跳

POST /v1/client/license/heartbeat

{"license_id":"lic_xxx","device_id":"dev_xxx","cfg_ver":9}

心跳会更新在线状态、设备最后在线时间/IP。超过 offline_after_s 未心跳视为离线。授权被冻结、吊销或过期时返回对应错误码。

TCP AGP/2

只给一键注入壳使用，普通 SDK 请走 HTTP。默认端口 9443。

1. 客户端发送长度前缀的 ClientHello（app_id、kid、X25519 公钥、nonce）；
2. 服务端返回 ServerHello + Ed25519 签名；
3. 双方用 X25519 + HKDF-SHA256 派生双向密钥；
4. 后续帧为 20 字节头 + ChaCha20-Poly1305 密文。

错误码

SDK 接入

推荐把 app_id、内置 Ed25519 公钥、设备指纹和 HTTP 基地址打包进客户端。卡密兑换和心跳使用设备 token；用户密码模式使用终端用户 token。

• 不要在客户端硬编码服务端私钥或卡密 pepper；
• 版本更新通过配置接口读取，低于强制更新版本时阻断；
• 设备指纹变化时走换绑流程，是否扣时长由软件设置决定；
• 服务端返回的防调试/虚拟机开关由 SDK 侧执行。