6. HWID 设备验证模块

设备指纹（HWID）验证相关接口。通过浏览器采集设备指纹（Canvas + GPU ID）绑定到玩家，用于反作弊机器验证。

6.1 拉起设备验证

由服务端（如 MCDR）调用，为玩家创建设备验证会话，返回验证链接。

接口: POST /hwid/upd

请求参数:

JSON
{
    "token": "aBcD1234EfGh5678IjKlMnOpQrSt",
    "player_id": "player123",
    "ip": "192.168.1.1"
}

Parameter	Type	Required	Description
token	string	Yes	认证 Token
player_id	string	Yes	玩家ID（无记录时必填）
ip	string	No	期望 IPv4 地址（用于 IP 一致性校验）
ipv6	string	No	期望 IPv6 地址

请求示例:

Bash
curl -X POST https://api.ndpreforged.com/hwid/upd \
  -H "Content-Type: application/json" \
  -d '{"token": "aBcD1234EfGh5678IjKlMnOpQrSt", "player_id": "player123"}'

响应示例 (200 OK):

JSON
{
    "session_id": "3f8a2c9e-...",
    "verify_url": "https://api.ndpreforged.com/hwid/verify/page/3f8a2c9e-...?code=...",
    "verify_code": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e",
    "expires_at": 1755384000,
    "message": "请玩家访问以下链接完成设备验证: https://..."
}

6.2 查询验证状态

MCDR 每秒轮询此接口，获取验证完成状态与封禁判定。

接口: POST /hwid/upd/check

Parameter	Type	Required	Description
token	string	Yes	认证 Token
session_id	string	Yes	验证会话ID

响应示例 (200 OK):

JSON
{
    "completed": true,
    "status": "completed",
    "player_id": "player123",
    "banned": false
}

completed: 是否完成验证

banned: 完成验证后附带封禁判定（未封禁时为 false）

status: pending / completed / expired / cancelled

6.3 作废验证会话

玩家重进或下线时调用，作废待处理的验证会话（幂等）。

接口: POST /hwid/upd/cancel

Parameter	Type	Required	Description
token	string	Yes	认证 Token
session_id	string	Yes	验证会话ID

响应示例 (200 OK):

JSON
{
    "cancelled": true,
    "session_id": "3f8a2c9e-..."
}

6.4 校验 HWID 封禁

校验指定设备指纹是否在封禁名单（支持限时封禁自动过期）。

接口: POST /hwid/auth

Parameter	Type	Required	Description
token	string	Yes	认证 Token
hwid	string	Yes	设备指纹（自动 SHA256 哈希）

响应示例 (200 OK):

JSON
{
    "banned": true,
    "whid_hash": "e3b0c44298fc1c149afbf4c8996fb924...",
    "reason": "作弊",
    "ban_time": "2026-08-15 12:00:00",
    "banned_until": null,
    "temporary": false
}

6.5 查询玩家 HWID 状态

查询玩家是否已绑定设备及封禁状态。

接口: POST /hwid/has

Parameter	Type	Required	Description
token	string	Yes	认证 Token
player_id	string	Yes	玩家ID

响应示例 (200 OK):

JSON
{
    "has_hwid": true,
    "banned": false
}

6.6 添加 HWID 封禁

添加设备封禁（需上传权限），支持限时封禁。

接口: POST /hwid/add

Parameter	Type	Required	Description
token	string	Yes	认证 Token（需上传权限）
hwid	string	Yes	设备指纹（自动哈希存储）
player_id	string	No	玩家ID
reason	string	No	封禁原因
ip	string	No	IP 地址
duration	int	No	限时封禁秒数（与 banned_until 二选一）
banned_until	string	No	到期时间 `YYYY-MM-DD HH:MM:SS`

响应示例 (200 OK):

JSON
{
    "message": "Added",
    "whid_hash": "e3b0c44298fc1c149afbf4c8996fb924...",
    "banned_until": null
}

6.7 删除 HWID 封禁

接口: POST /hwid/del

Parameter	Type	Required	Description
token	string	Yes	认证 Token（需上传权限）
hwid	string	Yes	设备指纹

响应示例 (200 OK):

JSON
{
    "message": "Removed"
}

6.8 绑定 HWID

将设备绑定到玩家记录（offline/online 表的 WHID 字段）。

接口: POST /hwid/bind

Parameter	Type	Required	Description
token	string	Yes	认证 Token（需上传权限）
hwid	string	Yes	设备指纹
player_id / ip / ipv6	string	Conditional	玩家标识（至少一个）

6.9 解绑 HWID

清除玩家记录中的 WHID 绑定。

接口: POST /hwid/cbind

Parameter	Type	Required	Description
token	string	Yes	认证 Token（需上传权限）
player_id / ip / ipv6	string	Conditional	玩家标识（至少一个）

6.10 浏览器验证流程

以下接口由验证网页内部调用，一般无需外部接入：

方法	端点	说明
GET	`/hwid/verify/page/<session_id>`	指纹采集网页（Canvas + GPU ID）
POST	`/hwid/verify/submit`	提交指纹（校验 verify_code + HMAC 签名）
POST/GET	`/hwid/verify/status`	查询会话状态（限流 10 次/分钟/IP）

6. HWID 设备验证模块

6.1 拉起设备验证

6.2 查询验证状态

6.3 作废验证会话

6.4 校验 HWID 封禁

6.5 查询玩家 HWID 状态

6.6 添加 HWID 封禁

6.7 删除 HWID 封禁

6.8 绑定 HWID

6.9 解绑 HWID

6.10 浏览器验证流程

导航