Skip to content

fix(server): require an auth token for the API server - #690

Open
Officeyutong wants to merge 2 commits into
nervosnetwork:developfrom
Officeyutong:fix/api-server-auth-token
Open

Officeyutong wants to merge 2 commits into
nervosnetwork:developfrom
Officeyutong:fix/api-server-auth-token

Conversation

@Officeyutong

Copy link
Copy Markdown
Contributor

What problem does this PR solve?

ckb-cli server --privkey-path exposes a transfer method that signs and sends a transfer to a caller-chosen address and amount, with no password or confirmation. The server has no authentication, and its CORS setting allows any origin. Listening only on 127.0.0.1 doesn't help, because a browser on the same machine can reach that address.

So any website opened while the server is running can call transfer with fetch() and drain the wallet.

What is changed and how it works?

  • Add the required --auth-token <token> option, and the server doesn't start without it. A request must carry the header Authorization: Bearer <token>, otherwise it gets 401 Unauthorized and no method is run. A website doesn't know the token, so this covers requests from any origin, including Origin: null and DNS rebinding.
  • OPTIONS requests don't need the token, because browsers don't send custom headers on CORS preflight and these requests don't run any method. This keeps browser clients that have the token working.
  • The token must be non-empty printable ASCII without spaces, and it is compared in constant time.
  • Update docs/API-Server.md.

Check List

Tests

  • Unit tests in src/subcommands/api_server.rs, which send raw HTTP requests to a real server:
    • requests with a missing or wrong token are rejected with 401 and don't run the method;
    • requests with the right token are processed;
    • OPTIONS requests don't run any method;
    • starting the server without --auth-token is a command line error.
  • Manual test with the built binary: starting without --auth-token fails; without a valid token POST gets 401, and with the token it reaches the RPC handler.
  • cargo clippy --all-targets with the CLIPPY_OPTS from the Makefile passes.

Side effects

  • Breaking change: every existing ckb-cli server setup must add --auth-token, and its clients must send the header. This includes setups without --privkey-path.
  • The token is given on the command line, so other local users can see it in the process list while the server is running.

Release note

Breaking: `ckb-cli server` now requires `--auth-token`, and clients must send `Authorization: Bearer <token>`. This stops websites from calling the local API server, including its `transfer` method.

@sunchengzhu

Copy link
Copy Markdown

Targeted API Server authentication regression tests passed against ckb-cli PR #690 commit 558a3648, but the documentation needs updates. I tested the versions before and after this fix on a local dev chain. Before the fix, I reproduced an unauthenticated transfer; with this PR, the same request returns 401 without moving funds. Authenticated transfer and get_capacity_by_address requests still work.

Coverage includes startup token validation; unauthenticated or invalid-token requests with Origin headers, in batches, and over persistent connections; authentication for read-only requests and servers without a private key; successful authenticated balance queries; unauthenticated CORS preflight; and valid transfers after a rejected request.

Could you update the authentication-related parts of docs/API-Server.md in this PR?

  1. The authentication text says every request needs a token and that any website able to reach the server can use its methods. OPTIONS requests are exempt and do not invoke RPC methods. A website can still send a request, but without the token it cannot make the server execute transfer.
  2. The transfer example uses $AUTH_TOKEN without defining it or showing how to start the server with the same token. The working get_capacity_by_address example also needs the Bearer header; copying it now returns 401.

I also found two non-blocking, pre-existing documentation mismatches that can be handled separately:

  1. The API list and examples advertise get_capacity_by_lock_hash and four get_live_cells_* methods, but the server registers only transfer and get_capacity_by_address. The two curl examples for those unavailable methods also lack the token header. They should be removed or marked unavailable rather than only given a header.
  2. The usage excerpt lists --wait-for-sync, which the server does not support. It also reproduces the CLI help's --listen-is-required wording, although the command accepts the default when that option is omitted; fixing this second inconsistency would require adjusting the CLI help or argument definition too.

针对 ckb-cli PR #690 提交 558a3648 的 API Server 认证回归测试已通过,但文档需要相应调整。 我在本地 dev 链上对比了修复前后的版本:旧版可以不带认证转账;新版会拒绝同样的请求并返回 401,资金不会转出。带正确 token 的 transfer 和 get_capacity_by_address 请求仍能正常执行。

用例覆盖启动时的 token 校验;缺失或错误 token 的请求(包括不同的 Origin、批量请求和长连接);只读查询和未配置私钥的服务也需认证;认证后的余额查询、无需认证的跨域预检,以及请求被拒绝后继续正常转账。

能否在这次 PR 中更新 docs/API-Server.md 中与认证有关的内容?

  1. 认证说明写着每个请求都需要 token,并说本机网页只要能访问服务就能调用接口。实际上 OPTIONS 请求免认证且不会执行 RPC 方法。网页仍可发送请求,但没有 token 就无法让服务执行 transfer。
  2. 转账示例使用了 $AUTH_TOKEN,却没有说明如何设置它,以及如何用同一个 token 启动服务。仍可使用的地址余额查询示例也缺少 Bearer 认证头,直接照着执行会得到 401。

另外还发现两处非阻塞的旧文档问题,可以后续处理:

  1. 接口列表和示例列有 get_capacity_by_lock_hash 和四个 get_live_cells_* 方法,但当前服务只注册了 transfer 和 get_capacity_by_address。那两处不可用方法的 curl 示例也缺少认证头;应删除这些条目或标明暂不可用,而不只是给示例补认证头。
  2. 命令用法摘录列出了服务端不支持的 --wait-for-sync。它还照录了命令帮助中 --listen 必填的说法,但实际不传该参数也会使用默认值;要彻底修正这一处,还需调整 CLI 的帮助文本或参数定义。

@allsafeareas

Copy link
Copy Markdown

i also check this

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants