HarmonyOS诊断字段脱敏规则与摘要校验【共创稿事节】

本地诊断事件完成字段分级后，还需要解决另一个工程问题：预览看到的内容与最终进入诊断包的字节必须一致。假设EV-104是一条导航超时事件，包含eventCode=NAV_TIMEOUT、elapsedMs=5320、pageKey=/pages/map以及联系邮箱。如果只在UI上把邮箱涂成星号，而导出模块继续读取未经处理的对象，敏感信息仍会被写入文件。因此，脱敏步骤必须输出一个独立的新对象，后续序列化、摘要计算和文件写入都只能接收它。

这里沿用前一篇建立的字段分类：公共字段一项，内部字段两项，敏感字段一项，秘密字段一项。输入对象包含五个业务字段；输出只保留四个，其中邮箱成为遮盖后的表示，临时令牌被彻底删除。应用可以让用户了解字段处理的变化，但不需要暴露原始凭据。事件的时间与编号属于外部标识，用于选择记录和复核对应关系，不以它们代替内容摘要。

让规则驱动输出而不是让页面拼接结果

长期维护的诊断工具经常经历字段增减。若每个页面都写一段字符串替换逻辑，新增字段后很容易出现一个页面遮盖、另一个页面直出的情况。规则表应成为唯一入口：公共和内部字段按业务需求保留，敏感字段使用明确定义的变换，秘密字段删除；不在白名单中的键默认拒绝进入输出。规则应随业务数据模型一起审阅并写入回归测试，尤其要检查异常响应中的消息、堆栈和动态参数，防止它们绕过正常采集路径。

邮箱遮盖不能依赖简单替换所有数字，因为用户名可能含有数字、汉字或分隔符，域名也不能随意被截断。下面采用易于复核的规则：保留本地部分前四个字符，后续用三个星号替代，并保持域名。这个规则只用于本文的示例邮箱；实际应用需要明确是否连域名也属于敏感信息。格式不符合预期时拒绝输出，比原样返回更稳妥。对于令牌，删除键要在创建新对象时发生，而不是先复制全部字段再等页面决定是否显示。

第一段代码通过规则表统一处理四种级别。即使输入对象携带authToken，结果的键集合也不包含它。测试同时检查遮盖结果和输出数量，能捕捉规则被误改后的直接信息泄漏。这里的控制逻辑适合作为ArkTS业务层适配时的纯函数核心，也可以在Node.js中以相同断言校验。

const assert = require('node:assert/strict');
const rules = Object.freeze({
  eventCode: 'keep', elapsedMs: 'keep', pageKey: 'keep',
  contactEmail: 'mask-email', authToken: 'drop'
});
function maskEmail(value) {
  const match = /^([^@]+)@([^@]+)$/.exec(String(value));
  if (!match) throw new TypeError('INVALID_EMAIL');
  return `${match[1].slice(0, 4)}***@${match[2]}`;
}
function sanitize(raw) {
  const result = Object.create(null);
  for (const [field, action] of Object.entries(rules)) {
    if (!Object.hasOwn(raw, field) || action === 'drop') continue;
    result[field] = action === 'mask-email' ? maskEmail(raw[field]) : raw[field];
  }
  return result;
}
const input = {eventCode:'NAV_TIMEOUT', elapsedMs:5320,
  pageKey:'/pages/map', contactEmail:'user123@example.com',
  authToken:'placeholder-token'};
const cleaned = sanitize(input);
assert.equal(cleaned.contactEmail, 'user***@example.com');
assert.equal(Object.hasOwn(cleaned,'authToken'), false);
assert.equal(Object.keys(cleaned).length, 4);
console.log(cleaned);

在大规模事件处理中，最好将原始输入的生存期限制在当前函数调用范围内。原始对象可能来自网络响应、导航异常或表单状态，传给脱敏函数后应尽快释放调用者不再需要的引用。缓存只能持有脱敏结果，事件列表也只读取这份结果。这样，当用户打开不同的页面、切换不同的设备布局时，输出内容的安全属性保持一致，不因UI实现方式而发生差异。

内容摘要为什么需要固定序列化

如果对JavaScript对象直接调用JSON.stringify，属性插入顺序可能使语义相同的对象产生不同字符串。对于存储、导入与跨版本对照，摘要的输入必须先稳定化。一个可行的应用层契约是按字段名称排序，对数字、字符串、布尔值使用规范的JSON表示；数组保持业务顺序，嵌套对象递归排序。这里专门处理JSON可表示的数据。undefined、循环引用、非有限数和特殊时间对象应在进入规范化器之前被拒绝或归一化，不能指望任意JavaScript值都得到可比的结果。

第二段Node.js代码实现了针对规范数据的递归稳定序列化，并通过内置crypto计算SHA-256内容摘要。它证明不同插入顺序可以得到同一摘要，并断言摘要以64个十六进制字符表示。摘要是内容指纹，不包含业务身份，也不能在缺乏签名或可信传输的情况下保证文件来自某个发布方。为避免误判，计算摘要时应明确覆盖的字段集、字符编码和序列化契约版本。

const assert = require('node:assert/strict');
const {createHash} = require('node:crypto');
function stable(value) {
  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
  if (value && typeof value === 'object') {
    return '{' + Object.keys(value).sort().map(k =>
      JSON.stringify(k) + ':' + stable(value[k])).join(',') + '}';
  }
  return JSON.stringify(value);
}
function digest(value) {
  return createHash('sha256').update(stable(value), 'utf8').digest('hex');
}
const one = {eventCode:'NAV_TIMEOUT', elapsedMs:5320,
  pageKey:'/pages/map', contactEmail:'user***@example.com'};
const two = {contactEmail:'user***@example.com', pageKey:'/pages/map',
  elapsedMs:5320, eventCode:'NAV_TIMEOUT'};
assert.equal(stable(one), stable(two));
assert.equal(digest(one), digest(two));
assert.equal(digest(one).length, 64);
console.log(digest(one));

对于EV-104，规范化内容包含eventCode、elapsedMs、pageKey和遮盖后的contactEmail。若摘要先于邮箱遮盖计算，摘要会和最终文件的真实内容不一致，也会让输入路径对敏感字段产生不必要依赖。正确的处理顺序是先完成规则校验，再生成受控对象，最后按固定编码生成摘要。展示摘要时可以只显示前若干字符，完整64字符摘要保存在与内容对应的清单字段里；预览中的缩略显示不应参与自动比较。

校验时比较的是内容而不是显示状态

页面展示绿色“核对通过”，只有在实际读取要交付的受控对象并重新计算摘要后才有意义。若用户修改了elapsedMs，即使事件编号与时间完全相同，也应视为内容变化。摘要计算还要把字段名本身纳入序列化，避免不同业务含义却恰好拼出相同字符串的情况。对于固定字段集合，可以再加一层结构约束：缺字段和多字段都属于协议不一致，而不能被静默补全后继续通过。

第三段代码把允许输出的四个键写成有序契约，用SHA-256生成二进制摘要，再用定长比较检查结果。它既检查原内容可被核对，也检查单个耗时值变化会使摘要失配，并拒绝携带额外令牌键的对象。固定长度比较适用于同类型摘要的比较流程，但真正的安全交付还必须考虑可信来源、权限控制与完整性保护，不能把内容摘要当作数字签名。

const assert = require('node:assert/strict');
const {createHash, timingSafeEqual} = require('node:crypto');
function canonical(fields) {
  const keys = ['contactEmail','elapsedMs','eventCode','pageKey'];
  if (keys.some(k => !Object.hasOwn(fields,k)) ||
      Object.keys(fields).some(k => !keys.includes(k))) {
    throw new Error('UNEXPECTED_FIELDS');
  }
  return JSON.stringify(Object.fromEntries(keys.map(k => [k,fields[k]])));
}
function contentHash(fields) {
  return createHash('sha256').update(canonical(fields),'utf8').digest();
}
function verify(fields, reference) {
  const actual = contentHash(fields);
  return Buffer.isBuffer(reference) && reference.length === actual.length &&
    timingSafeEqual(actual,reference);
}
const safe = {eventCode:'NAV_TIMEOUT', elapsedMs:5320,
  pageKey:'/pages/map', contactEmail:'user***@example.com'};
const reference = contentHash(safe);
assert.equal(verify({...safe},reference),true);
assert.equal(verify({...safe,elapsedMs:5321},reference),false);
assert.throws(() => contentHash({...safe,authToken:'x'}),/UNEXPECTED_FIELDS/);
console.log('digest verification checks passed');

这一层应明确区分三种错误。输入格式错误意味着某个字段不能按约定处理；脱敏策略错误意味着业务字段分类发生变化，需要重新审阅；内容摘要不一致意味着输出内容在不同环节之间出现了变化。三种错误如果都显示为“导出失败”，开发者无法根据状态采取措施。使用稳定的错误码和明确的人类可读解释，才能支持后续诊断包列表与异常恢复。

与HarmonyOS应用层的衔接

在HarmonyOS应用中，脱敏与摘要属于不依赖特定布局的纯业务处理。ArkUI页面只接收结果模型，例如outputFieldCount=4、removedFieldCount=1、digestState=matched，以及用于展示的安全字段。页面和导出模块都应从同一只读结果派生数据，不应分别再实现一次邮箱处理。列表焦点采用EV-104等稳定事件编号，即使排序、过滤或窗口宽度变化，选中的仍是同一事件，不会因列表位置改变而指向另一个记录。

文件写入应先在应用可写目录中完成临时结果，确认字节数、摘要与结构均一致后，再通过原子替换思路发布新的清单引用。具体文件接口与可用权限要以工程目标SDK和文件目录为准。对于向其他应用分享文件，华为开发者的文件共享接口强调基于URI进行授权，并需要考虑授权模式与释放流程。这里不借助文件共享接口执行Node.js内容校验，两者分工不同：纯函数确认数据结构，系统文件能力负责受控读写与分享。

界面图中的五个输入字段和四个输出字段应始终保持一致。contactEmail展示为user***@example.com，authToken在结果中显示“已移除”，不会在导出JSON里出现。内部字段pageKey=/pages/map可能揭示页面结构，是否保留应结合具体支持流程再次审视。若要把内部字段进一步转成区域类别，需要将这项变化纳入规则版本，并让摘要覆盖转换后的实际内容。不能在摘要生成后再对字段做二次替换，否则清单与文件失去对应关系。

版本兼容、权限与异常处理

规则表升级时，应给摘要契约单独的版本编号。旧记录如果缺少新字段，不应假设它在语义上与新记录一致；可以采用旧版解码器先还原为受控模型，再进行新版转换，并记录转换路径。对带有未知字段的旧数据，应隔离到本地问题列表，不直接加入交付包。字段顺序、Unicode规范化、数字表示和时间格式任一项变化，都可能影响摘要结果，因此回归样本需要覆盖中文、空字符串、邮箱异常、重复键输入以及边界数字。

在写入失败、磁盘空间不足或应用被中断的场景下，不能把尚未核对完整的文件标记为“可分享”。将待处理状态、摘要核对状态和最终发布状态区分开，可以让重试操作保持幂等。临时文件的清理由统一资源管理模块负责，失败后既要避免留下敏感原文，也要保留必要的匿名错误原因。后续导出包将使用本篇规范化对象作为唯一内容来源，形成可以从事件编号追溯到具体字节的完整链路。

参考文档

• 华为开发者：HiLog开发指导，https://developer.huawei.com/consumer/en/doc/atomic-guides-V5/atomic-hilog-development-V5
• 华为开发者：SHA-256安全检查规则，https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/ide-hmos-no-unsafe-hash
• 华为开发者：文件共享API，https://developer.huawei.com/consumer/en/doc/harmonyos-references-V13/js-apis-fileshare-V13

脱敏负责缩小被交付的数据范围，规范化负责让字节序列可重复生成，内容摘要负责发现后续的数据变化。把这三种职责拆成独立、可测试的处理环节，比在导出按钮的回调中堆叠全部逻辑更容易审阅，也更有利于未来替换持久化和分享实现。