Host、服务端、dev context 或持久化边界提供的普通反序列化数据;调用方不需要先做 类型断言。Proxy trap 或 getter 自身抛出的异常会原样传播。
ParsedMiniProgramRuntimePermissions。完整 snapshot 合法时返回
{ valid: true, permissions };顶层、entry、状态、重复 key 或已知 config 任一校验失败时统一
返回 { valid: false, permissions: {} },不会保留部分权限。
顶层必须是对象,schema_version 必须严格等于数字 1,entries 必须是数组。revision
可省略;存在时必须是大于或等于 0 的整数。revision 只参与输入校验,不会复制到返回值。
顶层与 entry 的其他字段会被忽略,以便 schema v1 内前向扩展。
每个 entry 必须是对象,key 必须是 trim 后非空的字符串,status 必须严格为
'enabled' 或 'disabled'。解析器先 trim key,再把唯一的历史别名 network.request
归一为 canonical network;大小写不会转换。重复检查基于归一化后的所有 key,因此
network 与 network.request 冲突,两个相同未知 future key 也会让整个 snapshot fail
closed。
是否属于当前受管 key 由 isManagedMiniProgramRuntimePermissionKey 与权限目录决定。
为兼容较新服务端,非空、状态合法且不重复的未知 key 会被忽略;其 config 可以缺失、为
null、数组或任意未来结构,均不会使已认识的权限失效。未知 entry 不会出现在返回映射中。
已知权限严格执行当前 schema:network 必须提供对象 config,且
useOfficialDomain 必须是 boolean;其他额外 network config 字段会丢弃,返回值只复制该
boolean。其余当前权限是无配置项权限,输入 config 可以缺失、为 null 或 {},并统一输出
{};非空对象、数组或其他值会使整个 snapshot 无效。Runtime snapshot 必须显式包含
network 的有效 boolean,即使 Manifest 目录把省略 useOfficialDomain 的开发者默认值定义为
false。
返回的 canonical entry/config 都是新对象;修改原 snapshot、entry 或嵌套 network config
不会改变解析结果。permissions 是 Partial map:合法空 entries、只包含未知权限,或没有某个
canonical key 时,解析仍可 valid: true,对应属性保持缺失。
valid: true 只表示 snapshot 可安全消费,不代表 entry 已启用,更不代表某个 capability 已获
授权。Runtime consumer 应先查 MINI_PROGRAM_PROTOCOL_CAPABILITIES 中目标 method 的
requirement:kind: 'none' 不读取权限;kind: 'all' 要求列出的每个 canonical entry 都存在
且 status === 'enabled'。之后仍需通过 Host capability、可信手势、用户授权、参数和业务
policy。当前 Runtime 对 valid: false 按空权限表 fail closed,受保护 method 会得到
PERMISSION_NOT_IN_SNAPSHOT,而不是沿用输入中的部分 enabled entry。
import { parseMiniProgramRuntimePermissions } from '@heybox/hb-sdk/protocol';
const parsed = parseMiniProgramRuntimePermissions({
schema_version: 1,
revision: 4,
entries: [
{
key: ' network.request ',
status: 'enabled',
config: { useOfficialDomain: false, futureField: 'discarded' },
},
{ key: 'future.permission', status: 'disabled', config: null },
],
});
// legacy key 已归一化;未知 future key 被忽略。
if (parsed.valid && parsed.permissions.network?.status === 'enabled') {
console.log(parsed.permissions.network.config.useOfficialDomain); // false
// 继续执行 capability requirement、Host 与业务 policy 校验。
}
将不可信的 schema v1 runtime permission snapshot 解析为独立的 canonical 权限映射。