【HarmonyOS 7新能力｜011】分布式数字身份入门实战：从能力边界到最小可运行链路
数字身份验证常见的错误做法，是为了证明一个简单条件而复制整份身份资料。例如业务只需确认用户是否满足某项条件，却要求上传姓名、证件号码和完整出生日期。分布式数字身份的工程价值之一，是让凭证由持有者控制，并围绕一次明确请求生成最小必要证明。
本文以“验证方请求证明某项资格，持有方确认后提交最小披露”为场景，建立创建挑战、选择凭证、用户确认、生成披露、验证签名和消费结果的应用侧链路。文中的 ArkTS 类型与流程属于建议模型，不是华为官方 API，也不代表某个特定 DID 或密码协议；凭证格式、算法、开放范围和安全要求请以 HarmonyOS 7 / API 26 当前官方资料为准。本文未完成安全认证或攻击验证。
一、先区分三种角色与责任
签发方对凭证中的声明负责；持有方保存凭证并决定是否披露；验证方提出有用途边界的请求并验证证明。三者不能混成一个“登录服务”，否则很难解释谁创建声明、谁授权披露、谁在什么范围内消费结果。
最小验收条件是：请求描述用途和必要声明；持有方能看懂并确认；证明绑定本次挑战与验证方；验证方检查签名、期限和会话；相同证明不能被再次使用；业务只获得完成动作所需结果。
角色边界还决定错误归属：签发信息有误由签发流程处理，用户拒绝披露不能记作验证失败，验证方自身挑战过期也不能要求持有方承担。把错误归到正确角色，才能设计合理重试与提示。
二、验证请求必须限定用途
请求不应只给出字段列表，还要说明验证目的、接收方、挑战值和有效期：
interface VerificationRequest { requestId: string verifierId: string purpose: string requiredClaims: string[] challenge: string expiresAt: number } type VerificationOutcome = 'verified' | 'rejected' | 'cancelled'purpose用于向用户解释，不应包含可执行指令。requiredClaims必须来自业务白名单；挑战由验证会话生成，不能重复或长期固定。
三、凭证选择不等于自动披露
钱包或凭证层可以找出满足声明要求的候选，但最终披露内容仍需显式计算并交给用户确认：
interface CredentialSummary { credentialId: string issuerLabel: string claimNames: string[] expiresAt?: number revoked?: boolean } function supports(credential: CredentialSummary, claims: string[]): boolean { if (credential.revoked) return false return claims.every(name => credential.claimNames.includes(name)) }摘要不包含原始敏感值。候选凭证有多个时，不应暗自选择权限最大的一个；优先选择披露更少且仍满足请求的凭证，必要时让用户决定。
四、声明最小化由请求交集决定
应用不得把凭证中所有字段都塞进证明。可以先计算请求声明与凭证声明的交集，并拒绝未知字段：
interface DisclosurePlan { requestId: string credentialId: string disclosedClaims: string[] omittedClaims: string[] } function planClaims(requested: string[], available: string[]): string[] { const allowed = new Set(available) return [...new Set(requested)].filter(name => allowed.has(name)) }若业务只需要布尔结论，应优先披露“条件满足”，而不是支撑结论的完整原始字段。具体是否支持这种证明及其密码学实现，必须由官方能力和所采用标准确认。
五、完整链路必须绑定一次挑战
验证方先创建带期限的随机挑战；持有方选择可用凭证并展示披露计划；用户确认后生成最小证明；验证方检查签名、挑战、接收方、用途和期限；成功结果只能在本次请求范围内消费一次。
挑战过期、声明缺失或会话不匹配都应拒绝并重新发起，不能沿用旧证明补字段。一次证明只服务一次明确请求，是防重放和防用途扩张的基础。
六、用户确认页面不能模糊处理
确认页至少应展示验证方、用途、将披露的声明和可取消入口。不要只显示“是否授权”，也不要把必要声明和可选声明混在一起。用户取消后，生成任务和临时披露计划必须失效。
确认页展示的是语义摘要，不直接渲染未经处理的验证方自由文本。长文本要截断并提供详情入口，深浅色、字体放大和读屏状态下仍需可理解。
如果披露计划在确认期间发生变化，例如凭证过期或请求被更新，旧确认立即作废并重新展示。不能把用户对旧字段集合的同意延伸到新增声明。
七、证明对象需要明确上下文
下面只描述应用侧封装，不定义真实密码字段：
interface PresentationEnvelope { presentationId: string requestId: string verifierId: string challenge: string purpose: string disclosedClaims: Record<string, string | boolean> createdAt: number expiresAt: number proof: string }proof必须由官方或经过审查的可信能力生成，不能自行拼接哈希冒充签名。应用层只传递不透明证明，并保证上下文字段与用户确认内容一致。
八、验证顺序要先上下文后业务
验证方收到证明后，先检查请求是否存在、是否过期、是否已消费，再检查接收方、挑战和用途是否一致，之后才调用可信签名验证，最后检查必要声明。
function matchesRequest( envelope: PresentationEnvelope, request: VerificationRequest, now: number ): boolean { return envelope.requestId === request.requestId && envelope.verifierId === request.verifierId && envelope.challenge === request.challenge && envelope.purpose === request.purpose && now <= request.expiresAt && now <= envelope.expiresAt }上下文不匹配时立即停止，不把失败证明送入业务逻辑。签名有效也不代表用途、期限和声明范围必然正确。
九、防重放需要原子消费
只在内存里先查询“未使用”，再异步标记“已使用”，会产生并发窗口。验证成功与消费标记应形成单一原子结果：
interface ConsumptionRecord { presentationId: string requestId: string consumedAt: number } interface ConsumeResult { accepted: boolean reason?: 'replayed' | 'expired' | 'invalid' | 'missing_request' }同一证明并发到达时只能有一个请求成功。记录保留周期应按安全与隐私要求设计，只保存防重放需要的最小标识和时间，不保存整份披露内容。
十、四层架构隔离密钥与页面
交互层负责验证请求、披露确认和结果反馈；会话层负责挑战管理、用途绑定与防重放；凭证层选择凭证、最小化声明并请求证明；可信适配层封装密钥、签名验证和安全存储能力。
页面不能读取私钥或原始密钥句柄，验证业务也不应自行实现密码算法。各层通过窄接口传递请求和最小证明，错误只返回稳定原因码。
十一、生命周期与数据清理同样重要
页面退出、用户取消、挑战过期或应用切换账号时，应销毁披露计划和临时证明，停止相关异步任务。迟到结果必须携带会话修订号，不能重新唤醒已经结束的确认页。
日志不得写入完整凭证、披露值、证明正文、私钥材料或稳定身份标识。确需审计时，只记录请求类别、结果原因、策略版本和去标识时间，并明确保存期限与访问边界。
清理验证不只检查页面变量，还要确认挑战计时器、凭证订阅和待完成回调已解除。恢复页面时重新查询请求状态，绝不能凭本地缓存再次提交旧证明。
十二、测试矩阵与落地清单
测试至少覆盖无匹配凭证、多个候选、声明缺失、用户取消、挑战过期、验证方不匹配、用途变化、签名失败、证明过期、并发重放、消费记录失败和页面恢复。每项都断言披露字段、最终结果、消费次数和临时数据清理。
集成验证还应覆盖凭证撤销或状态变化、设备迁移、深浅色、长文案与无障碍。密码算法、安全存储和跨设备行为必须使用官方能力与真实环境验证；本文未执行这些测试，不提供认证结论。
落地前确认官方开放范围；角色责任明确；请求包含用途、接收方、挑战和期限；披露字段是最小交集；用户看到完整摘要；证明绑定请求上下文；验证顺序正确；消费原子且防重放；密钥不进入页面；取消和过期统一清理。
分布式数字身份的核心不是把传统证件搬到设备里，而是让每次验证只披露必要内容，并且只对一个明确会话有效。先把请求、凭证、证明和消费边界建模清楚，再接入 HarmonyOS 7 的实际可信能力，才能真正减少身份数据暴露。
参考资料：
- HarmonyOS 开发者能力介绍：https://developer.huawei.com/consumer/cn/features/
- HarmonyOS 新特性发布说明：https://developer.huawei.com/consumer/cn/doc/doccenter-release-notes/os-new-feature-2600
