【Leona】BoxId 是什么-设备指纹参数

BoxId 是什么从Leona.sense()到/v1/verdict的可落地闭环签名、落库、错误处理与回归验证基于公开示例TL;DRBoxId 不是“风险结论”而是一次“证据报告兑换券”端上拿 BoxId后端换证据报告。/v1/verdict公开合约是后端接口必须用 SecretKey 签名请求并明确标注为single-use因此后端落库/缓存是硬要求。公开仓库提供了多语言后端示例入口examples/boxid-verdict/Python/Java/Go/Node/C/C。本文把这些公开事实串成一条能直接照着做的最小闭环并给出可复制的测试向量。发布摘要移动对抗安全的工程化落地关键不是端上堆更多检测点而是把链路做对端上只上报证据并返回 BoxId后端用 SecretKey 请求签名调用/v1/verdict换证据报告并落库业务策略在后端输出 allow/challenge/deny并留下可审计的证据快照。本文只基于公开仓库内容README examples/boxid-verdict讲清楚合约、签名、single-use 语义、落库结构、错误处理与回归验证。0) 三条硬规则违反任意一条都等于把系统送给攻击者SecretKey 永远只在后端客户端不允许持有也不允许直接调用/v1/verdict。BoxId 只做透传端上不要基于本地结论做放行/拦截。证据报告必须落库/缓存因为/v1/verdict在公开 README 中明确标注为 single-use。1) 端到端最小闭环可以按这个顺序实现/验收App调用Leona.sense()上报证据 → 得到BoxIdApp → 业务后端在登录/支付/发帖等请求里携带BoxId业务后端 → LeonaPOST /v1/verdictSecretKey 签名换取证据报告业务后端落库/缓存证据报告BoxId 单次消费业务后端按分层策略输出动作allow/challenge/deny并审计这条链路的本质是把“最终决策出口”从 APK 移出并把解释性与可治理性放到后端。2)/v1/verdict公开合约后端调用EndpointPOST https://leona.xiyanshan.com/v1/verdictBody{boxId:01KR0000000000000000000000}Headers后端构造Authorization: Bearer LEONA_SECRET_KEYContent-Type: application/jsonX-Leona-Timestamp: unix-time-msX-Leona-Nonce: random-nonceX-Leona-Signature: base64url-hmac-sha256签名算法公开说明signingText timestamp \n nonce \n sha256(requestBody) signature base64url_no_padding(HMAC-SHA256(secretKey, signingText))工程化解读nonce timestamp防重放body sha256防篡改。你应该把“timestamp 窗口错误 / nonce 重放 / 签名不匹配”当成可观测的失败类型记录到日志与指标后面排障会省很多时间。3) 直接可用的多语言实现来自公开仓库 examples下面代码片段来自公开仓库examples/boxid-verdict/你可以用它们作为后端集成最小参考实现。3.1 Node.jsexamples/boxid-verdict/nodejs/query_boxid.mjsimportcryptofromnode:crypto;constbodyJSON.stringify({boxId});consttimestampDate.now().toString();constnoncecrypto.randomBytes(16).toString(base64url);constbodySha256crypto.createHash(sha256).update(body).digest(hex);constsigningText${timestamp}\n${nonce}\n${bodySha256};constsignaturecrypto.createHmac(sha256,secret).update(signingText).digest(base64url);3.2 Pythonexamples/boxid-verdict/python/query_boxid.pybodyjson.dumps({boxId:box_id},separators(,,:)).encode(utf-8)timestampstr(int(time.time()*1000))noncebase64url_no_padding(secrets.token_bytes(16))body_sha256hashlib.sha256(body).hexdigest()signing_textf{timestamp}\n{nonce}\n{body_sha256}.encode(utf-8)signaturebase64url_no_padding(hmac.new(secret.encode(utf-8),signing_text,hashlib.sha256).digest())3.3 Goexamples/boxid-verdict/go/query_boxid.gobody,_:json.Marshal(map[string]string{boxId:boxID})timestamp:fmt.Sprintf(%d,time.Now().UnixMilli())nonce:base64.RawURLEncoding.EncodeToString(randomBytes(16))bodyHash:sha256.Sum256(body)signingText:fmt.Sprintf(%s\n%s\n%s,timestamp,nonce,hex.EncodeToString(bodyHash[:]))signature:base64.RawURLEncoding.EncodeToString(hmacSha256([]byte(secret),[]byte(signingText)))说明三种语言虽然写法不同但签名输入字符串完全一致timestamp\nnonce\nsha256(body)。4) “验收级”测试固定测试向量先把签名实现锁死很多集成问题不是“服务端不稳定”而是签名实现细节不一致JSON 是否有空格、是否 base64url、是否去 padding、timestamp 单位等。建议你先做一个“固定输入 → 固定输出”的单元测试把签名实现锁死。4.1 测试向量可直接复制secretKey sk_test_123timestamp 1700000000000nonce nonce_testbody {boxId:01KR0000000000000000000000}注意JSON 必须无多余空格计算结果body_sha256_hex 1d6530c70bc08d977158e83fb8fc5a11ef08490cabfdec17fa54f392e4754a45signature_base64url _Yjj8KhRfxMEnGaoRJrRKNtp_LOO2pNi2ndTzh9bLhs4.2 Node.js 测试片段示例importcryptofromnode:crypto;functionsign(secret,timestamp,nonce,body){constbodySha256crypto.createHash(sha256).update(body).digest(hex);constsigningText${timestamp}\n${nonce}\n${bodySha256};returncrypto.createHmac(sha256,secret).update(signingText).digest(base64url);}constbody{boxId:01KR0000000000000000000000};constsigsign(sk_test_123,1700000000000,nonce_test,body);if(sig!_Yjj8KhRfxMEnGaoRJrRKNtp_LOO2pNi2ndTzh9bLhs)thrownewError(signature mismatch);只要这个测试过了你再去联调线上接口定位问题会简单很多。5) single-use 语义后端落库/缓存不是可选项公开 README 明确/v1/verdict是 single-use成功查询会消费 BoxId。这会直接影响你的业务实现不要以“需要时再查一次”为前提要把证据报告当成业务决策的一部分落库并绑定业务 request/order/user。5.1 推荐最小落库字段公开字段boxIddeviceFingerprintcanonicalDeviceIdeventsauthoritativeRiskTags/telemetryRiskTagsriskTagsBySourceprovenance、policyExplanation5.2 最小 SQL 表结构示例createtableleona_verdict_cache(box_idtextprimarykey,canonical_device_idtext,device_fingerprinttext,evidence_json jsonbnotnull,created_at timestamptznotnulldefaultnow(),business_user_idtext,business_request_idtext);6) 错误处理与指标把“集成”做成可运维的系统建议你至少打这些指标/v1/verdict成功率、P95 延迟4xx/5xx 分布尤其是签名类错误与窗口类错误证据报告落库成功率challenge 触发率/通过率如果你有挑战日志建议永远不要打印 SecretKey记录boxId、requestId、status、error_type、latency_ms7) 策略落地一个务实的分层模板配合公开字段不要把某个 tag 直接等价成封禁。一个能跑起来、也能承受误报的最小模板是authoritative 高信任证据命中 → challenge 或 deny按业务风险分级中性环境证据模拟器/云机等→ 结合业务上下文新号/高价值更严telemetry 低信任证据 → 只用于解释/调试与回溯不直接触发拦截公开字段authoritativeRiskTags与telemetryRiskTags的分离本质就是为了让你写出这种“可治理”的策略。8) 你能从公开仓库得到哪些“可验证事实”而不是空谈合约事实/v1/verdict的签名算法与 single-use 语义写在公开 README/示例里。示例事实examples/boxid-verdict/提供多语言实现。边界事实公开仓库反复强调“SDK 不做最终决策后端自决”。标签BoxId后端集成请求签名证据落库风控策略CTAGitHub欢迎 starhttps://github.com/zedbully/leona-open项目主页https://leona.xiyanshan.com/9) 把“示例脚本”升级成“生产可用服务”你真正要写的不是脚本而是一个可运维的后端组件公开仓库里的examples/boxid-verdict/很有价值它把签名算法、请求头、body 哈希等关键细节写成了可运行代码。但在真实业务里你不会在主业务进程里直接python query_boxid.py。你需要的是一个可复用、可观测、可回滚的“Leona 证据兑换组件”。一个比较稳妥的做法是把它做成你后端内部的一个模块或一个独立服务并明确它的职责边界输入boxId 业务上下文userId / requestId / riskTier 等输出证据报告落库后返回 reportId 或摘要以及策略动作allow/challenge/deny约束任何情况下不泄漏 SecretKey不把/v1/verdict暴露给客户端下面给一个“够用但不复杂”的 Node.jsTypeScript 风格示例展示如何把脚本升级成服务。9.1 组件划分推荐leonaClient只负责签名与调用/v1/verdictverdictStore只负责落库与幂等decisionEngine只负责把 evidence report businessCtx → decisionapi只负责暴露内部接口给业务系统调用绝不对外10) 生产级示例实现一个“BoxId 兑换 落库 决策”内部 API10.1 Express 路由内部使用importexpressfromexpress;import{queryVerdict}from./leonaClient;import{saveVerdictOnce,getCachedVerdictByBoxId}from./verdictStore;import{decide}from./decisionEngine;constappexpress();app.use(express.json());// 内部接口业务后端调用不要暴露公网app.post(/internal/leona/exchange,async(req,res){const{boxId,userId,requestId,isHighValue}req.body;if(!boxId||!userId||!requestId)returnres.status(400).json({error:missing fields});// 1) 幂等同一个 boxId 被重复请求时先尝试从缓存/数据库读取constcachedawaitgetCachedVerdictByBoxId(boxId);if(cached){constdecisiondecide(cached.report,{userId,requestId,isHighValue});returnres.json({source:cache,decision,report:cached.reportSummary});}// 2) 兑换调用 /v1/verdict 换取证据报告single-use务必尽快落库constreportawaitqueryVerdict(boxId);// 3) 落库用 boxId 做唯一键保证并发下不会写入两份awaitsaveVerdictOnce({boxId,userId,requestId,report});// 4) 决策示例决策真实业务一般要引入风控等级与灰度constdecisiondecide(report,{userId,requestId,isHighValue});returnres.json({source:live,decision,report:{boxId,canonicalDeviceId:report.canonicalDeviceId}});});app.listen(3000);这个路由做了几件关键的“工程正确事情”先查缓存/落库结果幂等再做兑换避免重复消费 BoxId兑换成功后立刻落库single-use 语义要求决策在后端做且可以把isHighValue等业务上下文纳入10.2leonaClient严格复用公开签名算法签名算法千万不要“凭感觉重写”最好的方式是直接以公开examples/boxid-verdict/nodejs/query_boxid.mjs为基准提取成函数再加上本文第 4 节的“固定测试向量”单测锁死实现细节importcryptofromnode:crypto;constDEFAULT_ENDPOINThttps://leona.xiyanshan.com/v1/verdict;exportasyncfunctionqueryVerdict(boxId:string){constsecretKeyprocess.env.LEONA_SECRET_KEY!;constendpointprocess.env.LEONA_ENDPOINT||DEFAULT_ENDPOINT;constbodyJSON.stringify({boxId});consttimestampDate.now().toString();constnoncecrypto.randomBytes(16).toString(base64url);constbodySha256crypto.createHash(sha256).update(body).digest(hex);constsigningText${timestamp}\n${nonce}\n${bodySha256};constsignaturecrypto.createHmac(sha256,secretKey).update(signingText).digest(base64url);constrespawaitfetch(endpoint,{method:POST,headers:{Authorization:Bearer${secretKey},Content-Type:application/json,X-Leona-Timestamp:timestamp,X-Leona-Nonce:nonce,X-Leona-Signature:signature,},body,});consttextawaitresp.text();if(!resp.ok)thrownewError(verdict failed:${resp.status}${text});returnJSON.parse(text);}注意上面示例为了讲清楚直接写了Authorization: Bearer secretKey公开契约如此。生产系统里你至少要禁止把 secretKey 写入任何日志把异常文本做截断记录 error_type签名/时间窗/网络/5xx而不是原文。11) 幂等与并发single-use 语义下最容易踩坑的“竞态条件”一旦你把/v1/verdict接到生产流量里马上会遇到并发问题同一个请求被重试客户端重发、网关重试、队列重投同一个用户触发多个并行业务请求多端、并发点击业务链路里有多个模块都试图“查询一次”在 single-use 语义下最危险的情况是两个并发请求同时去兑换同一个 BoxId其中一个成功、另一个失败然后你在业务里把失败当成“系统不稳定”。解决方案是把幂等写进后端以boxId作为唯一键落库用“先查后写 唯一约束”或“事务/锁”保证并发下只写入一次11.1 Postgres 幂等落库示意createtableleona_verdict_cache(box_idtextprimarykey,report_json jsonbnotnull,created_at timestamptznotnulldefaultnow());写入时使用insert ... on conflict do nothing然后再读回如果写入成功说明你是第一个兑换者如果冲突说明另一个并发已经写入你直接读取即可这类“幂等 唯一键”是生产系统里处理 single-use token 的常规套路。12) 错误分类error taxonomy不要把所有失败都当成“HTTP 500”把错误分类做清楚会直接提升你集成上线后的排障速度。建议至少分这几类你可以按业务需要扩展auth_failedSecretKey 错误/权限错误signature_mismatch签名不匹配实现错误、body 不一致、base64url/padding 差异timestamp_skew时间窗错误设备/环境时钟偏移、重放保护nonce_replaynonce 重放network_timeout网络超时upstream_5xx上游 5xxboxid_consumedBoxId 已被消费通常是并发/重试导致重要的是你的业务决策系统需要知道“失败是否可重试”。network_timeout可能可重试但要避免重试导致二次消费signature_mismatch不可重试必须修代码timestamp_skew可能可恢复校时/重建 session但要可诊断13) 回归测试把“能跑”变成“可持续迭代”如果你想把这条链路长期维护下去至少需要三层测试13.1 签名单元测试必须有用本文的固定测试向量锁死签名实现避免某次重构把 JSON 序列化或 base64url 细节改坏。13.2 合约测试contract test把请求头、body 结构、必填字段做成测试缺 header 应当失败body JSON 多空格/字段名大小写不一致是否会导致签名不一致13.3 业务回归policy regression把历史 evidence report 落库之后你就能做策略回放同一批历史样本在策略 v1/v2 下的 decision 分布变化clean OEM 样本是否被误杀这在 v0.2.0 公开计划里被当成门禁这一步很关键它把“安全”从一次性集成变成持续工程。14) 你最终应该交付什么给团队的验收物清单如果你在团队里推动这个落地我建议你把验收物写成“可以看、可以跑、可以回归”的东西一个内部接口/internal/leona/exchange或等价一个落库表leona_verdict_cache或等价一套签名单测固定向量 base64url/sha256 校验一套指标与告警成功率、P95、错误分类、落库成功率一份集成 runbook怎么排查签名失败、时间窗错误、并发消费做到这些你的“BoxId → 证据报告 → 策略动作”链路才算真正进入生产形态。15) 签名实现最容易踩的 10 个坑几乎都发生在“细节不一致”下面这些坑你只要踩过一次就会记一辈子。把它们写进团队的 code review checklist会比事后排障省很多时间。timestamp 单位错秒 vs 毫秒。公开契约里是unix-time-ms。nonce 不够随机不要用递增数或时间戳当 nonce至少 16 bytes 随机。base64 与 base64url 混用header 里要求 base64url//要替换为-/_。padding 处理不一致有的实现去掉有的保留。公开示例使用“不带 padding”。JSON 序列化不稳定字段顺序、空格、换行不同都会导致 body hash 不同。bodySha256 计算对象错必须对“最终发送的 body 字节”做 sha256而不是对某个对象结构。签名输入拼接错必须是timestamp \n nonce \n sha256(body)换行符与顺序必须一致。字符编码不一致一定要 UTF-8。把 secretKey 当成 token 打印到日志这类事故一旦发生唯一正确动作是立刻换钥并做安全事件复盘。把错误信息原样回传给客户端尤其在 5xx/签名错误时不要把上游响应原文透传给前端。把这些坑写成 checklist 后工程质量会有肉眼可见的提升。16) JSON 规范化为什么 Python 示例要写separators(,, :)你会注意到公开 Python 示例里有一句json.dumps({boxId:box_id},separators(,,:))这不是“代码洁癖”而是为了保证 body 的字节序列稳定。签名里要对 requestBody 做 sha256。如果你的 JSON 序列化会插入多余空格{boxId: xxx}vs{boxId:xxx}它们语义相同但字节不同sha256 不同签名自然不同。因此在任何语言里你都应该把“最终发送的 body 字节序列”固定下来NodeJSON.stringify默认没有空格一般稳定。Python显式指定 separators避免空格。Java/Go确保输出的 JSON 与你计算 hash 的 JSON 完全一致。最保险的方式仍然是用固定测试向量做单测把“body 的精确字符串”也锁死。17) BoxId 在业务链路里怎么传字段命名、追踪与审计BoxId 的使用不应该是“临时加个字段”。你需要把它当成一种业务级证据关联键。17.1 建议的字段策略App → 后端建议使用明确字段名例如leonaBoxIdbody 字段或X-Leona-BoxIdheader。后端内部统一叫boxId并把它写入 request context便于链路追踪。17.2 追踪Tracing建议为每次兑换建立requestId业务已有就复用。日志里记录requestId、userId、boxId、decision、error_type、latency_ms。把“兑换发生在哪个业务动作”也记录下来login/payment/posting。这样你的证据链才真正可审计你能回答“这个用户为什么被挑战/拒绝”。18) 重试策略什么能重试、什么绝不能重试single-use 语义让重试变得微妙你既想提高可用性又不能因为重试导致二次消费与混乱。建议把重试分成两层18.1 后端调用/v1/verdict的重试谨慎只对“明显未到达上游”的错误做一次短重试例如连接建立失败DNS/网络瞬断一旦你已经拿到明确的 HTTP 响应尤其是非 2xx不要盲目重试。18.2 业务侧的重试幂等 查缓存优先业务侧如果要重试同一个 boxId必须先查缓存/落库结果查不到再考虑兑换如果你把“查缓存优先”做对了大部分重试都不会触发二次消费。19) 证据落库的扩展字段你未来一定会想要这些前面给了最小落库字段但真实系统上线后你往往会想要更多字段来支持运营与回归decision当时的动作allow/challenge/denypolicy_version策略版本号用于回放risk_tier业务风险等级高价值/低价值app_version/sdk_version定位某次版本引入的误报country/region、network_type解释性维度注意合规这些字段不需要一口气全上但你要给 schema 留扩展空间。20) 把文章写“更像实战”的最后一招给出验收问答你把下面这组问答贴到 PR 描述或上线评审里基本就能把讨论从“水文”拉到工程层面问BoxId 兑换失败时我们能区分是签名问题还是网络问题吗答能。我们有固定签名单测 error taxonomy 指标分布。问BoxId 被并发消费时会发生什么答后端以 boxId 为唯一键落库先查缓存再兑换并发下只会写入一份其他请求走缓存。问策略误杀如何回滚答策略版本化在后端灰度发布回滚不依赖发版证据报告落库可回放回归。问SecretKey 泄漏的应急预案是什么答立刻换钥 排查泄漏路径 回收日志/权限 补监控告警。这四问四答能把“是否能用”说得非常清楚。21) 性能与成本为什么“先落库再决策”反而更省钱很多团队担心“多一次后端调用会不会太慢、太贵”。实际工程里只要你把缓存与落库做对证据链往往是可控的/v1/verdict只在关键业务动作发生时调用登录/支付/发帖/领券不是每个请求都调。single-use 语义要求你落库落库后同一业务链路的后续查询都走你自己的缓存/数据库不再打上游。决策在后端做意味着你可以把策略做成“轻量函数”不需要端上复杂计算。更重要的是你用落库换来的是“可审计、可回放、可回归”的工程能力这会显著降低误报治理的人力成本。22) 隐私与合规证据链要可用也要可控做设备/环境证据链时务必把“最小必要”原则写进规范只持久化业务确实需要的字段给证据报告设置访问权限与留存周期例如 30/90/180 天日志与指标避免记录敏感原文优先记录聚合统计与错误类型如果需要用于模型训练或风控分析尽量做脱敏与分级授权。这部分不属于 Leona 专属而是任何“设备证据平台”都会面对的工程现实。23) 最后的落地建议把它当成“产品能力”交付给业务方如果你只把它当成一段调用代码半年后你会发现没有人维护、没有人敢改、出了事也没人能解释。更好的方式是把它当成“产品能力”交付有清晰的接口内部 API有明确的门禁与指标有可回放的证据落库有可灰度的策略版本做到这四点你的 BoxId 证据链才算真正进入“可持续”的状态。24) 一句话总结把 BoxId 当作“证据兑换券”把/v1/verdict当作“后端证据报告接口”再配上“幂等落库 错误分类 固定签名单测 分层策略”你就拥有了一条能上线、能运维、能迭代的移动端证据链。补充一句现实经验先把签名实现与幂等落库做对再谈策略与覆盖面否则你会在“到底是系统不稳定还是我们实现错了”的争论里浪费大量时间。当这条链路稳定后你会发现移动端安全讨论会从“谁更会写检测”转向“证据是否成立、策略是否合理、误报如何治理”——这才是工程化的胜利。