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

package/src/permissions.ts

@@ -2,6 +2,59 @@ import { MINI_PROGRAM_PERMISSION_KEYS, type MiniProgramPermissionKey } from './p
 
 const MANAGED_RUNTIME_PERMISSION_KEYS = new Set<string>(MINI_PROGRAM_PERMISSION_KEYS);
 
+/**
+ * 判断字符串是否是当前协议目录管理的 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 function isManagedMiniProgramRuntimePermissionKey(key: string): key is MiniProgramPermissionKey {
   return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
 }
@@ -16,11 +69,99 @@ 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 function parseMiniProgramRuntimePermissions(snapshot: unknown): ParsedMiniProgramRuntimePermissions {
   if (!isRecord(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
     return { valid: false, permissions: {} };

package/types/bridge.d.ts

@@ -42,14 +42,37 @@ export interface SDKCSPViolationPayload {
     sdkVersion: string;
     timestamp: number;
 }
+/**
+ * SDK 与 Host Runtime 跨 iframe 传输时共用的顶层 bridge envelope。
+ *
+ * @typeParam TPayload - 当前 method 对应的 payload 类型；未知或尚未按 method 收窄时默认为 `unknown`。
+ *
+ * @remarks
+ * 该类型刻意保留为宽 envelope，以同时表达 handshake、request、response、event 与 cancel。
+ * 字段组合的运行时约束由 {@link isMiniProgramBridgeMessage} 执行；v2 cancel 和 operation progress
+ * 可分别使用 {@link MiniProgramBridgeCancelMessage} 与 {@link MiniProgramBridgeProgressMessage}
+ * 获得更精确的静态类型。
+ *
+ * 类型匹配不建立信任边界。从 `postMessage` 接收数据时，先以 `unknown` 交给 guard，再独立校验
+ * `MessageEvent.source`、预期 nonce、握手状态，以及具体 method 的 payload；当 origin 可以固定且
+ * 当前协议模式要求时，再校验 `MessageEvent.origin`。
+ */
 export interface MiniProgramBridgeMessage<TPayload = unknown> {
+    /** 固定协议 namespace，用于从其他页面消息中识别候选 envelope。 */
     namespace: typeof MINI_PROGRAM_MESSAGE_NAMESPACE;
+    /** 当前消息采用的 wire 版本；新消息使用 v2，接收端为兼容握手接受 v1。 */
     version: 1 | 2;
+    /** Runtime 创建 iframe 时分配并由双方逐条回传的实例 nonce。 */
     nonce: string;
+    /** 决定 id、method、payload 与 error 组合规则的消息类别。 */
     type: MiniProgramBridgeMessageType;
+    /** 请求关联 ID；普通生命周期 event 可省略，request、response、handshake、cancel 与 progress 必须提供。 */
     id?: string;
+    /** capability 或事件名；response 可省略，cancel 禁止携带。 */
     method?: string;
+    /** method 对应的 wire payload；必须在按 method 分发后继续校验。 */
     payload?: TPayload;
+    /** 失败 response 的结构化错误；其他消息类型不得携带。 */
     error?: MiniProgramBridgeError;
 }
 export interface MiniProgramBridgeCancelMessage extends MiniProgramBridgeMessage<never> {

package/types/capabilities.d.ts

@@ -70,13 +70,32 @@ export type MiniProgramCompanionMethod = typeof COMPANION_GET_INFO_METHOD | type
 export type MiniProgramBridgeMethod = MiniProgramAuthMethod | MiniProgramUserMethod | MiniProgramShareMethod | MiniProgramViewportMethod | MiniProgramStorageMethod | MiniProgramNetworkMethod | MiniProgramFilesMethod | MiniProgramFileMethod | MiniProgramDirectoryMethod | MiniProgramUiMethod | MiniProgramDeviceMethod | MiniProgramNavigationMethod | MiniProgramCloudMethod | MiniProgramCompanionMethod;
 export type MiniProgramCapabilityModule = 'auth' | 'user' | 'share' | 'viewport' | 'storage' | 'network' | 'files' | 'file' | 'directory' | 'ui' | 'device' | 'navigation' | 'cloud' | 'companion';
 export type MiniProgramCapabilityRisk = 'low' | 'medium' | 'high';
+/** 单个公开 bridge method 的机器可读协议元数据。 */
 export interface MiniProgramCapabilityDefinition {
+    /** wire envelope 中使用的唯一 method 名。 */
     method: MiniProgramBridgeMethod;
+    /** 负责实现和分发该 method 的 capability module。 */
     module: MiniProgramCapabilityModule;
+    /** Runtime capability 开关使用的 key；当前公开协议中与 {@link method} 相同。 */
     capability: MiniProgramBridgeMethod;
+    /** Manifest 声明必须满足的权限组合；不替代权限状态、Host 支持或业务授权校验。 */
     requirement: MiniProgramPermissionRequirement;
+    /** 供审核、诊断和展示使用的静态风险分级；它本身不会执行安全策略。 */
     risk: MiniProgramCapabilityRisk;
 }
+/**
+ * 所有公开小程序 bridge method 的权威 method-level 目录。
+ *
+ * @remarks
+ * Host Runtime、文档生成器和一致性测试使用该目录判断 method 是否属于协议、由哪个 module
+ * 持有，以及调用前需要满足哪些声明权限。每个 {@link MiniProgramBridgeMethod} 必须且只能出现
+ * 一次；消费者不应另建 method、module、requirement 或 risk 的平行目录。
+ *
+ * 该目录只拥有 method metadata。精确 payload/result 类型分别由
+ * {@link MiniProgramCapabilityPayloadMap} 与 {@link MiniProgramCapabilityResultMap} 定义，权限的
+ * 展示名称、配置字段和平台审批属性由 `MINI_PROGRAM_PERMISSION_CATALOG` 定义。`kind: 'none'`
+ * 仅表示无需 Manifest 权限声明，不表示绕过参数校验、Host 能力、可信手势或业务策略。
+ */
 export declare const MINI_PROGRAM_PROTOCOL_CAPABILITIES: readonly [{
     readonly method: "auth.login";
     readonly module: "auth";

package/types/constants.d.ts

@@ -1,6 +1,28 @@
+/**
+ * 所有小程序 iframe bridge envelope 共用的固定 namespace。
+ *
+ * @remarks 该值用于排除无关 `postMessage` 数据，不负责验证消息来源；接收方仍须校验 source 和 nonce，
+ * 并在 origin 可以固定且协议模式要求时校验 origin。
+ */
 export declare const MINI_PROGRAM_MESSAGE_NAMESPACE: "heybox:miniprogram";
+/**
+ * 新消息默认发送的当前 bridge wire 版本。
+ *
+ * @remarks 接收 guard 为握手协商继续接受 v1 与 v2 envelope；cancel 与 operation progress 等 v2-only 消息仍必须使用 v2。
+ */
 export declare const MINI_PROGRAM_MESSAGE_VERSION: 2;
+/**
+ * Runtime 在 iframe URL 中传递 bridge nonce 的 query 参数名。
+ *
+ * @remarks nonce 用于把消息关联到当前 iframe 实例，不是独立的身份认证凭据；接收方还必须校验 source，
+ * 并在 origin 可以固定且协议模式要求时校验 origin。
+ */
 export declare const MINI_PROGRAM_BRIDGE_NONCE_PARAM: "hb_mini_bridge_nonce";
+/**
+ * SDK 发起 bridge 握手时使用的保留 method。
+ *
+ * @remarks `type: 'handshake'` 的消息必须使用该 method；Runtime 的可选握手响应也可携带该 method 供 SDK 识别环境快照。
+ */
 export declare const SDK_HANDSHAKE_METHOD: "sdk.handshake";
 export declare const RUNTIME_LOCATION_PROBE_METHOD: "runtime.location.probe";
 export declare const SDK_LOCATION_REPORT_METHOD: "sdk.location.report";