同租户、同规范化 Key 才能读回；Key 稳定性是密文数据合同的一部分。

✦ ① 先给结论：它保护的不是一段文本，而是一个作用域

很多加密 API 的心智模型是“有同一把密钥就能解”。接口引擎私有密文不是这样设计的。V8 脚本只交出明文；宿主从当前执行上下文取得 OsClient 和 ApiEngineKey，再构造不可由脚本改写的用途域。解密时必须回到同一租户、同一接口引擎作用域。

调用参数里没有 OsClient、ApiEngineKey、Purpose 或主密钥；作用域由可信宿主决定。

✦ ② Key 如何进入密文：规范化、摘要、Purpose

当前 BuildApiEngineSecretPurpose 会先对 ApiEngineKey 做 Trim 和 ToLowerInvariant，再对 UTF-8 字节计算 SHA-256，最后拼成 V8.ApiEngineSecret.<摘要>。

这个 Purpose 连同 OsClient 进入 TenantSystemSettingsSecurity，由可信宿主继续解析实际加密密钥。

只改大小写或首尾空格不会改变摘要；改字符、前缀或版本后缀会得到新的作用域。

normalizedKey = Trim(ApiEngineKey).ToLowerInvariant()
purpose = "V8.ApiEngineSecret." + SHA256(normalizedKey)

ProtectSecret(OsClient, purpose, plainText)
UnprotectSecret(OsClient, purpose, cipherText)

所以“换 Key 就失效”要说得更准确：语义上更换规范化后的 Key 才会改变 Purpose。把 Billing.Sync 改成 billing.sync 不会换作用域；改成 Billing.Sync.V2 会。

✦ ③ 为什么不直接把 Key 当作 AES 密钥

ApiEngineKey 是可见的资源标识，不是秘密。如果直接用它加密，任何知道 Key 的人都可能离线尝试解密。当前实现只把 Key 的摘要当作用途标识；真正的密钥由 TenantSystemSettingsSecurity 在可信宿主内按租户和用途解析，V8 脚本从未获得主密钥。

旧Key可信动作：读取指定记录 → 解密到受控内存
新Key可信动作：接收原文 → 立即重加密 → 回写新密文
验收：每条记录都有明确结果；原文不落日志、不进导出

• Key 参与隔离，但 Key 本身不是密码。
• OsClient 负责租户边界；同名 Key 在不同租户也不能互解。
• 接口只接受 plainText 或 cipherText，脚本不能自选 Purpose。
• 没有合法接口引擎上下文时，Protect/Unprotect 直接抛错。

✦ ④ 四种失败分别在保护什么

失败不是偶然兼容问题，而是租户、资源、执行面和完整性四条边界在起作用。

跨租户失败，防止 SaaS 数据串读；换 Key 失败，防止一个可编辑接口成为其它接口的通用解密器；缺上下文失败，防止普通 V8 事件借能力扩大权限；密文损坏失败，则要求调用方进入显式异常路径。

✦ ⑤ 改名看似运维动作，实际上可能改变数据可读性

如果接口只做无状态计算，改 ApiEngineKey 常被当成路由重命名。但只要它曾把第三方刷新 Token、远程连接密码等可逆凭据持久化，Key 就进入了密文的长期读取合同。先改 Key、再发布新包，会让新接口无法直接读取旧密文。

• 已有 Managed 引擎升级时，优先保持 Key 稳定。
• 确需新 Key 时，不要覆盖旧入口后立即删除。
• 先盘点所有密文字段、记录数量、业务归属和回滚点。
• 迁移必须在旧作用域解密、在新作用域重加密，并逐条业务回读。
• 整个过程继续执行用户、菜单、行归属、强身份和审计规则。

✦ ⑥ 安全迁移不是“解出来再批量导入”

保留旧入口 → 旧域解密 → 新域重加密 → 核对后切换；原文不落日志、不进列表。

真正危险的不是重加密本身，而是为了迁移临时创建一个“传 Key 就能解”的通用接口，或者把原文导出成文件。正确做法是让旧 Key 的可信动作只处理明确记录，新 Key 的动作只生成新密文，中间原文停留在受控调用内存中。

✦ ⑦ 证据边界：这篇文章确认了什么，没有确认什么

源码、接口、文档与 Skill 结论一致；定向测试被共享工作树的无关编译错误阻断。

本轮已交叉读取 V8Method、IV8Method、TenantSystemSettingsSecurity、官方中文 V8 文档和 v8-security Skill。它们对租户绑定、Key 绑定、参数边界与 Managed Key 稳定性给出一致合同。

本文没有把源码阅读包装成运行验证，也不提供未经执行结果支持的性能数字。生产仍需单独验证真实租户密文迁移、权限、审计、错误回滚和多节点发布；本轮构建阻断的精确原因仅保存在内部证据记录中。