docs: 明确 Cobo Auth Nonce 取值 - #377
Open
rcsh1 wants to merge 1 commit into
Open
Conversation
Collaborator
Author
运行过程记录（自动生成）本评论记录本次 doc 运行的内部过程，便于审查每个结论的来源。 1. 意图（确认后）Problem nonce-format-ambiguity: Evidence: inline feedback says "/developers/v2_cn/guides/overview/cobo-auth 里面的NONCE到底是随机字符串还是以毫秒为单位的当前 Unix 时间戳？" The suspected faulty doc is /developers/v2_cn/guides/overview/cobo-auth, specifically the Cobo Auth/NONCE description or signing example, because the wording leaves readers unable to tell whether NONCE must be an arbitrary random string or the current Unix timestamp in milliseconds. Category: Unclear or incomplete content. Documentation team should verify the authoritative behavior in code before editing: inspect the request authentication/signature validation path that reads the nonce header/field, any replay-protection or timestamp-window checks, and SDK request-signing helpers/examples that generate NONCE. Confirm whether the API accepts any unique random string, requires millisecond Unix time, or uses timestamp examples only as one valid nonce strategy; then update the page with an explicit rule, valid/invalid examples, and any uniqueness/time-window requirements. 2. 探索发现（按仓库 × explorer）
其他相关路径：
3. 综合结论综合结论：公开 WaaS2 Cobo Auth 的签名校验路径读取 confidence: high open_questions: 未发现公开 WaaS2 Cobo Auth 路径的 replay cache 或 timestamp-window 代码证据；只在 legacy internal 汇总代码证据清单： 4. 编辑计划[
{
"task_id": "clarify-cobo-auth-nonce-cn",
"action": "fix_docs",
"doc_file": "v2_cn/guides/overview/cobo-auth.mdx",
"repo_alias": "primary",
"doc_edit_description": "Clarify the Cobo Auth nonce wording in Chinese. Replace ambiguous uses of `随机数` that imply an arbitrary random value with `Nonce` / timestamp-focused wording. State that `Biz-Api-Nonce` is the nonce value included in the signing string and sent in the request header, that Cobo signing helpers generate it as the current Unix timestamp in milliseconds such as `1718587017026`, and that the header value must exactly match the `NONCE` component in `str_to_sign`. Add a valid example with the same millisecond timestamp in both places and an invalid example where the header and signing-string nonce differ or a stale signed pair is reused. Do not document a specific public replay/time-window rule.",
"code_evidence": [
"waas2/developers/api_key_sign_helper.py:57 — SDK/helper generates the nonce value from now_ms(), proving the documented client strategy is a millisecond Unix timestamp.",
"waas2/developers/api_key_sign_helper.py:98 — SDK/helper sends the same generated timestamp string in the Biz-Api-Nonce header.",
"waas2/authentications/universal_access_control/authentications/api_key_authentication.py:47 — Public WaaS2 auth reads biz-api-nonce from the request header as a header value.",
"waas2/authentications/universal_access_control/authentications/api_key_authentication.py:51 — Public WaaS2 auth builds canonical signed content from method, path, nonce, params, and body.",
"waas2/authentications/universal_access_control/authentications/api_key_authentication.py:63 — Public WaaS2 auth verifies the Ed25519 signature against the canonical string containing the nonce header value.",
"cobo-libs/cobo_libs/api/restful/utils/api_key_sign_helper.py:63 — Shared signing helper generates the nonce value with now_ms().",
"cobo-libs/cobo_libs/api/restful/utils/api_key_sign_helper.py:102 — Shared signing helper sends that generated timestamp as Biz-Api-Nonce."
],
"code_evidence_missing": false
},
{
"task_id": "clarify-cobo-auth-nonce-en",
"action": "fix_docs",
"doc_file": "v2/guides/overview/cobo-auth.mdx",
"repo_alias": "primary",
"doc_edit_description": "Mirror the nonce clarification in the English Cobo Auth guide. Keep `Biz-Api-Nonce` and `NONCE` identifiers untranslated, and add explicit prose that the nonce used by Cobo signing helpers is the current Unix timestamp in milliseconds, for example `1718587017026`; the same value must appear in the `Biz-Api-Nonce` header and the `NONCE` segment of `str_to_sign`. Add matching valid/invalid examples. Avoid claiming a public timestamp-window or replay-cache rule because code evidence only confirms such a window for the separate legacy `CUS_NONCE` path.",
"code_evidence": [
"waas2/developers/api_key_sign_helper.py:57 — SDK/helper generates the nonce value from now_ms(), proving the documented client strategy is a millisecond Unix timestamp.",
"waas2/developers/api_key_sign_helper.py:98 — SDK/helper sends the same generated timestamp string in the Biz-Api-Nonce header.",
"waas2/authentications/universal_access_control/authentications/api_key_authentication.py:47 — Public WaaS2 auth reads biz-api-nonce from the request header as a header value.",
"waas2/authentications/universal_access_control/authentications/api_key_authentication.py:51 — Public WaaS2 auth builds canonical signed content from method, path, nonce, params, and body.",
"waas2/authentications/universal_access_control/authentications/api_key_authentication.py:63 — Public WaaS2 auth verifies the Ed25519 signature against the canonical string containing the nonce header value.",
"cobo-libs/cobo_libs/api/restful/authentications/signature.py:84 — Shared EdDSA authentication reads biz-api-nonce from the request header as a string.",
"cobo-libs/cobo_libs/api/restful/authentications/signature.py:88 — Shared EdDSA verifier builds signed content from method, path, nonce, query params, and body.",
"cobo-libs/cobo_libs/api/restful/authentications/signature.py:97 — Shared EdDSA verifier validates the signature over that signed content.",
"cobo-libs/cobo_libs/api/restful/utils/api_key_sign_helper.py:63 — Shared signing helper generates the nonce value with now_ms().",
"cobo-libs/cobo_libs/api/restful/utils/api_key_sign_helper.py:102 — Shared signing helper sends that generated timestamp as Biz-Api-Nonce."
],
"code_evidence_missing": false
}
]5. 评审轮次最终评审结论：Approved。 6. 基线与同步编辑前同步到的 upstream 基线 commit： api-spec 同步结果：不适用，本次未修改 api-spec 源 YAML，也未同步 验证：在 |
Collaborator
Author
运行过程记录（自动生成）本评论记录本次 doc 运行的内部过程，便于审查每个结论的来源。 1. 意图（确认后）Problem nonce-format-ambiguity: Evidence: inline feedback says "/developers/v2_cn/guides/overview/cobo-auth 里面的NONCE到底是随机字符串还是以毫秒为单位的当前 Unix 时间戳？" The suspected faulty doc is /developers/v2_cn/guides/overview/cobo-auth, specifically the Cobo Auth/NONCE description or signing example, because the wording leaves readers unable to tell whether NONCE must be an arbitrary random string or the current Unix timestamp in milliseconds. Category: Unclear or incomplete content. Documentation team should verify the authoritative behavior in code before editing: inspect the request authentication/signature validation path that reads the nonce header/field, any replay-protection or timestamp-window checks, and SDK request-signing helpers/examples that generate NONCE. Confirm whether the API accepts any unique random string, requires millisecond Unix time, or uses timestamp examples only as one valid nonce strategy; then update the page with an explicit rule, valid/invalid examples, and any uniqueness/time-window requirements. 2. 探索发现（按仓库 × explorer）说明：原始探索记录较长；本节按 explorer 保留 findings、handoff_brief 与 code_evidence 要点，避免超过 GitHub 单评论长度限制。 Explorer b1 / branch b1findings:
handoff_brief:
code_evidence:
Explorer b1 / branch b2findings:
handoff_brief:
code_evidence:
Explorer b2 / branch b1findings:
handoff_brief:
code_evidence:
Explorer b2 / branch b2findings:
handoff_brief:
code_evidence:
Explorer b3 / branch b1findings:
handoff_brief:
code_evidence:
Explorer b3 / branch b2findings:
handoff_brief:
code_evidence:
Explorer b4 / branch b1findings:
handoff_brief:
code_evidence:
Explorer b4 / branch b2findings:
handoff_brief:
code_evidence:
3. 综合结论result: confidence: 0.82 open_questions:
汇总代码证据清单:
4. 编辑计划[
{
"task_id": "clarify-cobo-auth-nonce-cn",
"action": "fix_docs",
"doc_file": "v2_cn/guides/overview/cobo-auth.mdx",
"repo_alias": "primary",
"doc_edit_description": "Clarify the Cobo Auth nonce wording in Chinese. Replace ambiguous uses of `随机数` that imply an arbitrary random value with `Nonce` / timestamp-focused wording. State that `Biz-Api-Nonce` is the nonce value included in the signing string and sent in the request header, that Cobo signing helpers generate it as the current Unix timestamp in milliseconds such as `1718587017026`, and that the header value must exactly match the `NONCE` component in `str_to_sign`. Add a valid example with the same millisecond timestamp in both places and an invalid example where the header and signing-string nonce differ or a stale signed pair is reused. Do not document a specific public replay/time-window rule.",
"code_evidence": [
"waas2/developers/api_key_sign_helper.py:57 — SDK/helper generates the nonce value from now_ms(), proving the documented client strategy is a millisecond Unix timestamp.",
"waas2/developers/api_key_sign_helper.py:98 — SDK/helper sends the same generated timestamp string in the Biz-Api-Nonce header.",
"waas2/authentications/universal_access_control/authentications/api_key_authentication.py:47 — Public WaaS2 auth reads biz-api-nonce from the request header as a header value.",
"waas2/authentications/universal_access_control/authentications/api_key_authentication.py:51 — Public WaaS2 auth builds canonical signed content from method, path, nonce, params, and body.",
"waas2/authentications/universal_access_control/authentications/api_key_authentication.py:63 — Public WaaS2 auth verifies the Ed25519 signature against the canonical string containing the nonce header value.",
"cobo-libs/cobo_libs/api/restful/utils/api_key_sign_helper.py:63 — Shared signing helper generates the nonce value with now_ms().",
"cobo-libs/cobo_libs/api/restful/utils/api_key_sign_helper.py:102 — Shared signing helper sends that generated timestamp as Biz-Api-Nonce."
],
"code_evidence_missing": false
},
{
"task_id": "clarify-cobo-auth-nonce-en",
"action": "fix_docs",
"doc_file": "v2/guides/overview/cobo-auth.mdx",
"repo_alias": "primary",
"doc_edit_description": "Mirror the nonce clarification in the English Cobo Auth guide. Keep `Biz-Api-Nonce` and `NONCE` identifiers untranslated, and add explicit prose that the nonce used by Cobo signing helpers is the current Unix timestamp in milliseconds, for example `1718587017026`; the same value must appear in the `Biz-Api-Nonce` header and the `NONCE` segment of `str_to_sign`. Add matching valid/invalid examples. Avoid claiming a public timestamp-window or replay-cache rule because code evidence only confirms such a window for the separate legacy `CUS_NONCE` path.",
"code_evidence": [
"waas2/developers/api_key_sign_helper.py:57 — SDK/helper generates the nonce value from now_ms(), proving the documented client strategy is a millisecond Unix timestamp.",
"waas2/developers/api_key_sign_helper.py:98 — SDK/helper sends the same generated timestamp string in the Biz-Api-Nonce header.",
"waas2/authentications/universal_access_control/authentications/api_key_authentication.py:47 — Public WaaS2 auth reads biz-api-nonce from the request header as a header value.",
"waas2/authentications/universal_access_control/authentications/api_key_authentication.py:51 — Public WaaS2 auth builds canonical signed content from method, path, nonce, params, and body.",
"waas2/authentications/universal_access_control/authentications/api_key_authentication.py:63 — Public WaaS2 auth verifies the Ed25519 signature against the canonical string containing the nonce header value.",
"cobo-libs/cobo_libs/api/restful/authentications/signature.py:84 — Shared EdDSA authentication reads biz-api-nonce from the request header as a string.",
"cobo-libs/cobo_libs/api/restful/authentications/signature.py:88 — Shared EdDSA verifier builds signed content from method, path, nonce, query params, and body.",
"cobo-libs/cobo_libs/api/restful/authentications/signature.py:97 — Shared EdDSA verifier validates the signature over that signed content.",
"cobo-libs/cobo_libs/api/restful/utils/api_key_sign_helper.py:63 — Shared signing helper generates the nonce value with now_ms().",
"cobo-libs/cobo_libs/api/restful/utils/api_key_sign_helper.py:102 — Shared signing helper sends that generated timestamp as Biz-Api-Nonce."
],
"code_evidence_missing": false
}
]5. 评审轮次最终评审记录：
后续处理：
6. 基线与同步编辑前同步到的 upstream 基线 commit：执行者未报告。 api-spec 同步结果：不适用，本次未修改 api-spec 源 YAML，也未同步 Primary doc edits:
验证：
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
意图
本次变更来自对
/developers/v2_cn/guides/overview/cobo-auth中NONCE含义的反馈：现有表述让读者无法判断Biz-Api-Nonce到底是任意随机字符串，还是当前 Unix 毫秒时间戳。文档需要明确 Cobo Auth 签名流程中Biz-Api-Nonce与str_to_sign里的NONCE组件如何对应，并避免写入代码证据未能支撑的公开 replay/time-window 规则。变更摘要
v2_cn/guides/overview/cobo-auth.mdx：将Biz-Api-Nonce从“随机字符串”改为 Nonce，并说明 Cobo 签名辅助工具使用当前 Unix 毫秒时间戳，且请求头值必须与str_to_sign中的NONCE完全一致；补充有效和无效示例，减少中文读者对取值格式的歧义。v2/guides/overview/cobo-auth.mdx：同步英文 Cobo Auth 指南中的 Nonce 说明和匹配/不匹配示例，保持中英文文档规则一致。代码证据
waas2/developers/api_key_sign_helper.py:57：SDK/helper 通过now_ms()生成 nonce 值，证明文档中的客户端生成策略是当前 Unix 毫秒时间戳。waas2/developers/api_key_sign_helper.py:87：SDK/helper 将生成的时间戳作为 nonce 组件参与签名。waas2/developers/api_key_sign_helper.py:98：SDK/helper 将同一个生成的时间戳字符串发送到Biz-Api-Nonce请求头。waas2/authentications/universal_access_control/authentications/api_key_authentication.py:47：Public WaaS2 auth 从请求头读取biz-api-nonce。waas2/authentications/universal_access_control/authentications/api_key_authentication.py:51：Public WaaS2 auth 使用 method、path、nonce、params、body 构造签名原文。waas2/authentications/universal_access_control/authentications/api_key_authentication.py:63：Public WaaS2 auth 校验包含 nonce 请求头值的 Ed25519 签名。cobo-libs/cobo_libs/api/restful/authentications/signature.py:84：Shared EdDSA authentication 将biz-api-nonce作为字符串从请求头读取。cobo-libs/cobo_libs/api/restful/authentications/signature.py:88：Shared EdDSA verifier 使用 method、path、nonce、query params、body 构造签名原文。cobo-libs/cobo_libs/api/restful/authentications/signature.py:97：Shared EdDSA verifier 校验该签名原文上的签名。cobo-libs/cobo_libs/api/restful/utils/api_key_sign_helper.py:63：Shared signing helper 通过now_ms()生成 nonce 值。cobo-libs/cobo_libs/api/restful/utils/api_key_sign_helper.py:102：Shared signing helper 将生成的时间戳作为Biz-Api-Nonce发送。custody/api/base_internal_api.py:56：Legacy internal API 将CUS_NONCE解析为整数，说明这是另一条内部 nonce 路径。custody/api/base_internal_api.py:62：Legacy internal API 对CUS_NONCE执行毫秒时间窗口校验，因此本 PR 未将该内部路径的 time-window 规则写入公开 Cobo Auth 文档。无