@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...

    函数 parseMiniProgramRuntimePermissions

    • 将不可信的 schema v1 runtime permission snapshot 解析为独立的 canonical 权限映射。

      参数

      • snapshot: unknown

        Host、服务端、dev context 或持久化边界提供的普通反序列化数据;调用方不需要先做 类型断言。Proxy trap 或 getter 自身抛出的异常会原样传播。

      返回 ParsedMiniProgramRuntimePermissions

      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 校验。
      }

      0.6.4