LicenseV 授权验证 API

用于脚本/应用的授权验证。提供授权码校验、设备绑定、到期管理。

安全机制

防护措施	实现方式
防重放攻击	每次请求必须携带 X-Timestamp（Unix 秒）和 X-Nonce（随机串），同一 nonce 不可重复使用，时间戳误差不超过 90 秒
防伪造服务器	所有响应带 X-Signature 头 = HMAC-SHA256(响应体, 服务器密钥)，客户端可校验
防暴力破解	同一 IP 连续 5 次验证失败封禁 5 分钟；每 IP 每分钟最多 30 次请求
信息泄露	错误响应统一返回「验证失败」，不区分"key不存在""已过期""已禁用"
传输安全	强制 HTTPS，TLS 1.2+，HSTS
客户端加固	反调试检测 + 完整性自检（client.py 内置）

请求头要求

Header	值	说明
X-Timestamp	1756700000	当前 Unix 时间戳（秒），误差不得超过 ±90 秒
X-Nonce	a1b2c3d4e5f6...	16~128 字符随机字符串，每次请求不同，不可重复使用
Content-Type	application/json	固定值

// 生成要求的请求头（JavaScript）
const headers = {
  'Content-Type': 'application/json',
  'X-Timestamp': Math.floor(Date.now() / 1000).toString(),
  'X-Nonce': crypto.randomUUID(),
};

POST /api/verify

验证授权码，首次携带 device_id 自动绑定设备。

Request

{
  "key":        "YZ-XXXX-XXXX-XXXX",  // 必填
  "device_id":  "设备唯一标识",          // 可选，不传不绑定设备
  "device_name":"设备名称"              // 可选
}

Response 200

{
  "code":200, "message":"ok",
  "data":{
    "key":             "YZ-XXXX-XXXX-XXXX",
    "status":          "active",
    "expire_time":     "2027-05-09 23:59:59",  // null = 永久
    "expire_timestamp":1809835199,
    "days_left":       365,                      // null = 永久
    "never_expires":   false,
    "max_devices":     3,
    "device_bound":    true
  },
  "server_time":"2026-05-09 12:00:00",
  "nonce":"a1b2c3d4e5f6..."
}

响应头 X-Signature 包含 HMAC-SHA256 签名，可用于校验响应未被篡改。

错误响应（统一格式，不泄露具体原因）

{ "code":401, "message":"验证失败" }

POST /api/heartbeat

设备心跳。需先调用 verify 绑定设备。

Request

{ "key":"YZ-XXXX-XXXX-XXXX", "device_id":"设备唯一标识" }

Response 200

{ "code":200, "message":"ok", "data":{ "key":"...", "device_id":"...", "last_heartbeat":"2026-05-09 12:00:00" } }

GET /api/ping

连通性测试，无需鉴权头。

{ "code":200, "message":"pong", "data":{ "service":"LicenseV", "version":"3.0" } }

状态码

code	含义	处理
200	成功	继续执行
400	缺少安全头 / 时间戳过期 / nonce 重复	检查 X-Timestamp / X-Nonce
401	key 不存在	统一提示"验证失败"
403	key 已过期/禁用/IP限制/设备满	统一提示"验证失败"
404	接口不存在 / heartbeat 设备未绑定	先调 verify
429	触发频率/滥用限制	等待后重试

Python 示例

一行验证（推荐 — 使用内置 client.py）

from client import check
check("https://yanzheng.yunzai.love", "YZ-XXXX-XXXX-XXXX")

使用 requests（自行处理安全头）

import requests, time, secrets

r = requests.post("https://yanzheng.yunzai.love/api/verify",
    json={"key":"YZ-XXXX-XXXX-XXXX", "device_id":"my-device"},
    headers={
        "Content-Type": "application/json",
        "X-Timestamp": str(int(time.time())),
        "X-Nonce": secrets.token_hex(16),
    })
d = r.json()
if d["code"] == 200:
    print(f"✓ {d['data']['days_left']} 天")

curl 测试

# 生成安全头
TS=$(date +%s)
NC=$(openssl rand -hex 16)

# 验证
curl -X POST https://yanzheng.yunzai.love/api/verify \
  -H "Content-Type: application/json" \
  -H "X-Timestamp: $TS" \
  -H "X-Nonce: $NC" \
  -d '{"key":"YZ-XXXX-XXXX-XXXX","device_id":"test"}'

# 心跳
curl -X POST https://yanzheng.yunzai.love/api/heartbeat \
  -H "Content-Type: application/json" \
  -H "X-Timestamp: $TS" \
  -H "X-Nonce: $(openssl rand -hex 16)" \
  -d '{"key":"YZ-XXXX-XXXX-XXXX","device_id":"test"}'

# 连通测试（无需安全头）
curl https://yanzheng.yunzai.love/api/ping