@heybox/hb-sdk-protocol 0.8.2-alpha.1 → 0.8.2-alpha.2

package/types/permissions.d.ts

@@ -1,4 +1,57 @@
 import { type MiniProgramPermissionKey } from './permission-catalog';
+/**
+ * 判断字符串是否是当前协议目录管理的 canonical runtime permission key。
+ *
+ * @param key - 已确认类型为 `string` 的候选权限 key；若输入来自 `unknown` 边界，调用方须先完成字符串检查。
+ * @returns 与 `MINI_PROGRAM_PERMISSION_KEYS` 中某项精确相等时返回 `true`，并将 TypeScript 类型收窄为
+ * `MiniProgramPermissionKey`；未知、历史或格式不同的字符串返回 `false`。
+ *
+ * @remarks
+ * 当前 canonical key 集合固定为：
+ *
+ * - `userInfo`
+ * - `steamLibrary`
+ * - `share`
+ * - `storage`
+ * - `filesystem`
+ * - `clipboard`
+ * - `leaderboard`
+ * - `network`
+ * - `companion`
+ *
+ * 匹配大小写敏感且按原字符串执行。该 guard 不 trim，因此 `' network '` 返回 `false`；历史权限 key
+ * `network.request` 也返回 `false`，即使同名 capability method 仍是公开 method。消费完整 schema v1 权限快照时
+ * 应使用 {@link parseMiniProgramRuntimePermissions}，由解析边界统一 trim，并把历史 `network.request` 归一为
+ * canonical `network`。未知的 future key 同样返回 `false`；本 guard 不负责 parser 的前向兼容忽略策略。
+ *
+ * 类型谓词只把字符串收窄为 `MiniProgramPermissionKey` union，不读取权限 entry、status 或 config，也不检查
+ * Manifest。返回 `true` 不表示权限已声明、平台已批准、Runtime snapshot 中存在、status 为 `enabled`、Host 支持，
+ * 或当前 capability 已获准执行。尤其 `network` 与 `companion` 还需要平台批准；其他 declaration 权限也继续受
+ * 各自适用的 Host、用户授权、可信手势、参数与业务策略约束。
+ *
+ * `MINI_PROGRAM_PERMISSION_CATALOG` 提供每个 key 的展示信息、access、风险、配置字段和 method 集合；具体 bridge
+ * method 是否要求某项权限应以 {@link MINI_PROGRAM_PROTOCOL_CAPABILITIES} 的 `requirement` 为准。`kind: 'none'`
+ * 的 method 不会因为某个 key 被本 guard 识别而新增权限要求。
+ *
+ * @example
+ * ```ts
+ * import { isManagedMiniProgramRuntimePermissionKey } from '@heybox/hb-sdk/protocol';
+ *
+ * function acceptPermissionKey(candidate: unknown) {
+ *   if (typeof candidate !== 'string') return undefined;
+ *   return isManagedMiniProgramRuntimePermissionKey(candidate) ? candidate : undefined;
+ * }
+ *
+ * acceptPermissionKey('filesystem'); // 'filesystem'
+ * acceptPermissionKey('network'); // 'network'
+ * acceptPermissionKey(' network '); // undefined：guard 不 trim
+ * acceptPermissionKey('network.request'); // undefined：legacy key 只由 snapshot parser 归一化
+ * ```
+ *
+ * @see [parseMiniProgramRuntimePermissions](/reference/symbols/protocol/functions/parseMiniProgramRuntimePermissions) 完整 snapshot 的 trim、legacy 归一化与 config 校验。
+ * @see [MINI_PROGRAM_PROTOCOL_CAPABILITIES](/reference/symbols/protocol/constants/MINI_PROGRAM_PROTOCOL_CAPABILITIES) method 到 permission requirement 的权威映射。
+ * @see [权限声明](/guide/permissions) Manifest 声明、平台批准与 Runtime 状态的完整流程。
+ */
 export declare function isManagedMiniProgramRuntimePermissionKey(key: string): key is MiniProgramPermissionKey;
 export type MiniProgramRuntimePermissionStatus = 'enabled' | 'disabled';
 export interface MiniProgramRuntimePermissionEntry {
@@ -11,8 +64,96 @@ export interface MiniProgramRuntimePermissionsSnapshot {
     revision?: number;
     entries: MiniProgramRuntimePermissionEntry[];
 }
+/**
+ * `parseMiniProgramRuntimePermissions()` 返回的独立 canonical 视图。
+ *
+ * @remarks
+ * 结果不保留输入 snapshot、entries 或 config 的对象引用，也不包含 `schema_version`、`revision`
+ * 和未知权限。该对象不是授权决定；Runtime 还必须按 capability requirement、entry status、Host
+ * 能力和后续 policy 判断是否允许调用。
+ */
 export interface ParsedMiniProgramRuntimePermissions {
+    /**
+     * 整个 schema v1 snapshot 是否通过结构、重复 key 与已知 config 校验。`true` 不表示存在任何
+     * permission、任何 entry 为 `enabled`，也不表示 capability 已获授权。
+     */
     valid: boolean;
+    /**
+     * 仅包含当前协议认识的 canonical key。缺失 key 表示 snapshot 未声明该权限；`disabled` entry
+     * 仍会保留。`valid: false` 时该映射必为空，解析器不会暴露部分成功结果。
+     */
     permissions: Partial<Record<MiniProgramPermissionKey, MiniProgramRuntimePermissionEntry>>;
 }
+/**
+ * 将不可信的 schema v1 runtime permission snapshot 解析为独立的 canonical 权限映射。
+ *
+ * @param snapshot - Host、服务端、dev context 或持久化边界提供的普通反序列化数据；调用方不需要先做
+ * 类型断言。Proxy trap 或 getter 自身抛出的异常会原样传播。
+ * @returns {@link ParsedMiniProgramRuntimePermissions}。完整 snapshot 合法时返回
+ * `{ valid: true, permissions }`；顶层、entry、状态、重复 key 或已知 config 任一校验失败时统一
+ * 返回 `{ valid: false, permissions: {} }`，不会保留部分权限。
+ *
+ * @remarks
+ * 顶层必须是对象，`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 由 {@link 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 应先查 {@link 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_DECLARED`，而不是沿用输入中的部分 enabled entry。
+ *
+ * @example
+ * ```ts
+ * 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 校验。
+ * }
+ * ```
+ *
+ * @see {@link ParsedMiniProgramRuntimePermissions}
+ * @see {@link MiniProgramRuntimePermissionsSnapshot}
+ * @see {@link isManagedMiniProgramRuntimePermissionKey}
+ * @see {@link MINI_PROGRAM_PROTOCOL_CAPABILITIES}
+ * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+ */
 export declare function parseMiniProgramRuntimePermissions(snapshot: unknown): ParsedMiniProgramRuntimePermissions;