API 文档

方式一：跳转主站验证页下载

这种方式适合网页下载按钮。你不需要自己处理挑战、PoW、下载令牌，也不需要关心当前由哪个下载节点提供文件。

需要特别注意：这里要跳转的是主站地址，不是下载节点地址。外部前端应该把用户带到主站的验证页面，由主站完成验证、授权和节点选择，最后再跳转到真实下载节点开始下载。

验证页地址示例

https://fyhub.cn/fcl/1.3.0.9/FCL-release-1.3.0.9-arm64-v8a.apk

这里的 https://fyhub.cn 就是枫源镜像主站公共入口，不是某个下载节点的 public_download_base_url。

GET /api/public/v1/projects

拿到 project_id 后，前端可以查询该项目下有哪些版本和文件。返回结果里会包含 version、file_name、architecture、system、size_bytes、digest_sha256 和 available 等字段。

Example Request

GET /api/public/v1/projects/example/assets

Example Response

{
  "status": "success",
  "data": {
    "assets": [
      {
        "asset_id": "asset_123",
        "version": "v1.2.3",
        "file_name": "example-windows-amd64.zip",
        "architecture": "amd64",
        "system": "win",
        "available": true
      }
    ]
  }
}

前端可以根据这些字段生成下载按钮。用户点击按钮时，跳转到主站验证页：

https://fyhub.cn/example/v1.2.3/example-windows-amd64.zip

1. 展示下载验证页面。
2. 在浏览器中完成下载挑战计算。
3. 向主节点领取短时下载授权。
4. 选择可用下载节点。
5. 跳转到真实下载地址开始下载。

外部网站不要直接拼接节点下载地址，也不要调用程序下载用的 /api/public/v2/api/* 接口来替代这个流程。

方式二：程序调用 API 下载

这种方式适合命令行工具、自动更新器、CI 脚本、下载器或后端服务。程序需要自己查询资产、完成 API PoW 验证，然后携带下载令牌访问下载节点。

第一步：查询项目列表

查询当前已启用的项目列表并取得 project_id。项目即使暂时没有可路由下载资产也可能出现在结果中，应以 available 判断当前是否可下载。

Example Request

GET /api/public/v1/projects

Example Response

{
  "status": "success",
  "message": "查询成功",
  "request_id": "req_...",
  "data": {
    "projects": [
      {
        "project_id": "example",
        "repository": "owner/example",
        "display_name": "示例项目",
        "description": "示例说明",
        "homepage_url": "https://fyhub.cn",
        "available": true
      }
    ]
  }
}

第二步：查询项目资产

程序应选择一个 available=true 的资产，并记录它的 asset_id。如果 available=false，表示当前没有可用下载节点持有这个文件，程序应该稍后重试。

Example Request

GET /api/public/v1/projects/example/assets

Example Response

{
  "status": "success",
  "data": {
    "assets": [
      {
        "asset_id": "asset_123",
        "version": "v1.2.3",
        "download_path": "/example/v1.2.3/example.zip",
        "prerelease": false,
        "file_name": "example.zip",
        "architecture": "amd64",
        "system": "win",
        "size_bytes": 10485760,
        "digest_sha256": "0123456789abcdef...",
        "available": true,
        "unavailable_reason": ""
      }
    ]
  }
}

第三步：创建 API V2 顺序工作量挑战

旧版“下载授权协议 V1”弃用提醒：仅 /api/public/v1/api/challenges 与 /api/public/v1/api/authorizations 这两个旧 PoW/授权接口使用 SHA-256 前导零 nonce 搜索，并且当前部署可以直接关闭它们并返回 410 API_VERSION_RETIRED。这里不代表 /api/public/v1/ 下的项目、资产、封禁列表和更新日志接口被弃用。新客户端必须直接实现下面的 V2 repeated-squaring 流程，不能只替换接口路径。

为指定资产创建 3072 位 RSA repeated-squaring 挑战。响应中的 modulus 和 base 是 384 字节无符号大端整数的无填充 base64url 编码。

Example Request

POST /api/public/v2/api/challenges
{"asset_id":"asset_123"}

Example Response

{
  "status": "success",
  "data": {
    "challenge_id": "challenge_123",
    "asset_id": "asset_123",
    "algorithm": "rsa-repeated-squaring-v1",
    "modulus_id": "模数标识",
    "modulus": "512 字符 base64url 整数",
    "base": "512 字符 base64url 整数",
    "iterations": 96000,
    "encoding": "base64url-uint-be-384",
    "expires_at": "2026-09-03T12:05:00Z"
  }
}

第四步：顺序计算 solution

从 y = base 开始，严格执行 iterations 次 y = y² mod modulus，再把 y 编码为 384 字节定长大端 base64url。不得提交十进制、十六进制或可变长整数。

y = decode_unsigned_big_endian(base)
重复 iterations 次：
    y = (y × y) mod N
solution = base64url_no_padding(unsigned_big_endian_384(y))

# Mirror Server API V2 repeated-squaring 原理

## 用途

程序下载在调用 `POST /api/public/v2/api/challenges` 后，需要根据响应计算 `solution`，再提交到 `POST /api/public/v2/api/authorizations`。这是顺序工作量证明，不是 SHA 哈希 nonce 搜索。

## 挑战输入

- `algorithm` 必须是 `rsa-repeated-squaring-v1`。
- `encoding` 必须是 `base64url-uint-be-384`。
- `modulus`：RSA 模数 N，384 字节无符号大端整数的无填充 base64url，字符串长度 512。
- `base`：起始值，编码规则与 modulus 相同。
- `iterations`：服务端给出的最终迭代数，已经包含文件大小分档和风控倍率。
- `challenge_id` 和 `asset_id` 必须原样用于后续授权请求。

## 顺序算法

```text
N = decode_base64url_unsigned_big_endian_384(modulus)
y = decode_base64url_unsigned_big_endian_384(base)

repeat exactly iterations times:
    y = (y * y) mod N

solution_bytes = unsigned_big_endian(y, exactly 384 bytes, left padded with zeroes)
solution = base64url_without_padding(solution_bytes)
```

最终值在数学上是 `base^(2^iterations) mod N`。但客户端不知道 RSA 模数的陷门，无法化简指数；每轮又依赖前一轮结果，因此不能把迭代区间拆给多个线程后再合并。正确实现是一条顺序模平方循环。

## 编码边界

1. modulus、base、solution 在线上都固定为 384 字节、512 个 base64url 字符。
2. 整数按无符号大端解释，不能使用十进制、十六进制或可变长字节串。
3. solution 前导零必须保留到 384 字节。
4. base64url 使用 `-` 和 `_`，不得包含 `=` padding。
5. solution 必须满足 `0 < solution < N`。

## 授权请求

```json
{
  "challenge_id": "挑战响应中的 challenge_id",
  "asset_id": "创建挑战时使用的 asset_id",
  "solution": "512 字符定长 base64url 结果"
}
```

挑战会绑定 API V2、算法、资产、客户端网络前缀和有效期，并且成功授权后只能消费一次。不要跨资产、跨 Web/API 或跨 V1/V2 复用挑战；挑战过期或失败后应重新创建。

## 服务端校验原理

主节点持有仅存在于内存中的 RSA 陷门，可以快速计算相同最终值。创建挑战时保存的是定长预期结果的摘要；授权时先检查挑战绑定关系和生命周期，再检查 solution 的定长编码、数值范围和摘要。RSA 陷门、预期答案和 solution 都不会写入独立 PoW 遥测日志。

第五步：提交 solution 并领取下载授权

提交顺序工作量结果并领取短时、单节点绑定的下载授权。challenge_id、asset_id 与 solution 都必须来自同一条 V2 挑战链路。程序 API 当前没有需要客户端上报的 telemetry 字段。

Example Request

POST /api/public/v2/api/authorizations
{"challenge_id":"challenge_123","asset_id":"asset_123","solution":"512 字符 base64url 整数"}

Example Response

{
  "status": "success",
  "data": {
    "authorization_id": "auth_123",
    "download_url": "由服务端返回的实际下载节点 URL",
    "download_token": "43 字符短时随机令牌",
    "expires_at": "2026-09-03T12:05:00Z",
    "range_concurrency_limit": 32,
    "max_bytes": 20971520
  }
}

第六步：请求下载节点

程序应直接访问授权响应里的 download_url，并通过请求头携带 download_token。download_url 通常指向下载节点；授权成功后实际文件请求允许从与挑战阶段不同的出口访问，但令牌属于 Bearer 凭据，泄露后可能被他人使用。客户端还应遵守响应中的 range_concurrency_limit 与 max_bytes。

Example Request

GET {download_url}
Authorization: Bearer <download_token>

如果需要断点续传，可以使用单段 Range：

GET {download_url}
Authorization: Bearer <download_token>
Range: bytes=1048576-2097151

其他接口

下面这些接口不是程序下载流程的步骤，只用于订阅、状态查询或排障。