API Docs

Method 1: redirect to the main-site verification page

This method is suitable for web download buttons. You do not need to handle challenges, PoW or download tokens yourself, and you do not need to know which download node currently serves the file.

Important: redirect to the main-site address, not a download-node address. External front ends should send users to the main-site verification page, where verification, authorization and node selection are completed before redirecting to the actual download node.

Verification URL example

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

https://fyhub.cn is the public entry point of Maple Mirror, not a download node's public_download_base_url.

GET /api/public/v1/projects

After obtaining project_id, query the versions and files for that project. The response includes fields such as version, file_name, architecture, system, size_bytes, digest_sha256 and 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
      }
    ]
  }
}

The front end can use these fields to create a download button. When the user clicks it, redirect to the main-site verification page:

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

1. Show the download verification page.
2. Solve the download challenge in the browser.
3. Obtain short-lived download authorization from the main node.
4. Choose an available download node.
5. Redirect to the real download URL.

External sites must not construct node download URLs directly or replace this flow with the programmatic /api/public/v2/api/* endpoints.

Method 2: download through the programmatic API

This method is suitable for command-line tools, auto-updaters, CI scripts, downloaders and backend services. The program must query assets, complete API PoW verification and then use the download token to access a download node.

Step 1: query the project list

Query the currently enabled projects and obtain project_id. A project may still appear while no routable download asset is available, so use available to decide whether it can be downloaded now.

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
      }
    ]
  }
}

Step 2: query project assets

Choose an asset with available=true and record its asset_id. If available=false, no available download node currently holds the file, so retry later.

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": ""
      }
    ]
  }
}

Step 3: create an API V2 sequential-work challenge

Legacy “download authorization protocol V1” deprecation notice: only /api/public/v1/api/challenges and /api/public/v1/api/authorizations use SHA-256 leading-zero nonce search, and a deployment may already disable them and return 410 API_VERSION_RETIRED. This does not deprecate project, asset, blocklist or changelog endpoints under /api/public/v1/. New clients must implement the V2 repeated-squaring flow below rather than only replacing endpoint paths.

Create a 3072-bit RSA repeated-squaring challenge for an asset. The modulus and base in the response are unpadded base64url encodings of 384-byte unsigned big-endian integers.

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"
  }
}

Step 4: compute the solution sequentially

Starting from y = base, perform y = y² mod modulus exactly iterations times, then encode y as a fixed-length 384-byte big-endian base64url value. Do not submit a decimal, hexadecimal or variable-length integer.

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 遥测日志。

Step 5: submit the solution and obtain authorization

Submit the sequential-work result to obtain short-lived authorization bound to one node. challenge_id, asset_id and solution must all belong to the same V2 challenge flow. The programmatic API currently has no telemetry fields that clients need to report.

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
  }
}

Step 6: request the download node

Access download_url directly and send download_token in the request header. It normally points to a download node. After authorization succeeds, the actual file request may use a different egress from the challenge stage, but the token is a Bearer credential and can be used by whoever possesses it. Also honor range_concurrency_limit and max_bytes from the response.

Example Request

GET {download_url}
Authorization: Bearer <download_token>

For resumable downloads, use a single Range segment:

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

Other interfaces

These interfaces are not steps in the programmatic download flow; they are for subscriptions, status queries and troubleshooting.