{
  "openapi": "3.0.3",
  "info": {
    "title": "KeyForge License API",
    "version": "1.0.0",
    "description": "软件授权接口：激活、验证、换绑、续期。所有请求需 HMAC-SHA256 签名。"
  },
  "servers": [{ "url": "/", "description": "当前站点" }],
  "tags": [
    { "name": "License", "description": "授权生命周期" }
  ],
  "components": {
    "securitySchemes": {
      "LicenseSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "同时需要 X-App-Id、X-Timestamp、X-Nonce、X-Signature。签名：HMAC-SHA256(secret, timestamp + '\\n' + nonce + '\\n' + rawBody)"
      }
    },
    "schemas": {
      "ApiResponse": {
        "type": "object",
        "required": ["success", "code", "message"],
        "properties": {
          "success": { "type": "boolean" },
          "code": { "type": "integer", "example": 0 },
          "message": { "type": "string" },
          "data": { "nullable": true }
        }
      },
      "ActivateRequest": {
        "type": "object",
        "required": ["app_id", "license_key", "device_id"],
        "properties": {
          "app_id": { "type": "string", "example": "quant_pro" },
          "license_key": { "type": "string", "example": "K8F2-X7QM-92LA-P6TZ" },
          "device_id": { "type": "string", "example": "DEVICE-001" },
          "version": { "type": "string", "example": "1.0.0" }
        }
      },
      "VerifyRequest": {
        "type": "object",
        "required": ["app_id", "license_key", "device_id"],
        "properties": {
          "app_id": { "type": "string" },
          "license_key": { "type": "string" },
          "device_id": { "type": "string" },
          "version": { "type": "string" }
        }
      },
      "RebindRequest": {
        "type": "object",
        "required": ["license_key", "device_id"],
        "properties": {
          "license_key": { "type": "string" },
          "device_id": { "type": "string", "description": "新设备 ID" }
        }
      },
      "RenewRequest": {
        "type": "object",
        "required": ["app_id", "license_key", "renew_key"],
        "properties": {
          "app_id": { "type": "string" },
          "license_key": { "type": "string", "description": "当前已激活卡密" },
          "renew_key": { "type": "string", "description": "未使用的同商品续期卡密" },
          "device_id": { "type": "string" }
        }
      }
    }
  },
  "security": [{ "LicenseSignature": [] }],
  "paths": {
    "/api/v1/license/activate": {
      "post": {
        "tags": ["License"],
        "summary": "激活授权",
        "operationId": "activateLicense",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateRequest" } } }
        },
        "responses": {
          "200": {
            "description": "授权成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": {
                  "success": true,
                  "code": 0,
                  "message": "授权成功",
                  "data": {
                    "license_id": "LIC_123456",
                    "status": "active",
                    "expires_at": "2027-08-24T00:00:00.000Z",
                    "device_id": "DEVICE-001"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/license/verify": {
      "post": {
        "tags": ["License"],
        "summary": "验证授权",
        "operationId": "verifyLicense",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" } } }
        },
        "responses": {
          "200": {
            "description": "授权有效",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": {
                  "success": true,
                  "code": 0,
                  "message": "授权有效",
                  "data": {
                    "status": "active",
                    "expires_at": "2027-08-24T00:00:00.000Z",
                    "days_remaining": 365,
                    "device_bound": true
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/license/rebind": {
      "post": {
        "tags": ["License"],
        "summary": "换绑设备",
        "operationId": "rebindLicense",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RebindRequest" } } }
        },
        "responses": {
          "200": {
            "description": "换绑成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": {
                  "success": true,
                  "code": 0,
                  "message": "换绑成功",
                  "data": { "device_id": "DEVICE-002", "remaining_rebinds": 2 }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/security/report": {
      "post": {
        "tags": ["License"],
        "summary": "异常上报并自动封禁",
        "operationId": "reportTamper",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["reason"],
                "properties": {
                  "app_id": { "type": "string" },
                  "license_key": { "type": "string" },
                  "device_id": { "type": "string" },
                  "reason": { "type": "string", "enum": ["decompile", "debugger", "integrity", "crack", "tamper"] },
                  "detail": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已记录并封禁",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": {
                  "success": true,
                  "code": 0,
                  "message": "已记录并封禁",
                  "data": {
                    "report_id": "clx_report_1",
                    "reason": "decompile",
                    "banned": ["device", "license", "license_key"],
                    "license_id": "LIC_123456",
                    "device_id": "DEVICE-001"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/license/renew": {
      "post": {
        "tags": ["License"],
        "summary": "续期授权",
        "operationId": "renewLicense",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewRequest" } } }
        },
        "responses": {
          "200": {
            "description": "续期成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" },
                "example": {
                  "success": true,
                  "code": 0,
                  "message": "续期成功",
                  "data": {
                    "license_id": "LIC_123456",
                    "status": "active",
                    "expires_at": "2027-09-23T00:00:00.000Z"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}