@heybox/hb-sdk-protocol 0.9.1-alpha.1 → 0.9.1-alpha.10

package/types/permission-catalog.d.ts

@@ -1,117 +0,0 @@
-import type { MiniProgramBridgeMethod, MiniProgramCapabilityRisk } from './capabilities';
-export declare const MINI_PROGRAM_PERMISSION_KEYS: readonly ["userInfo", "steamLibrary", "share", "storage", "filesystem", "clipboard", "leaderboard", "network", "companion"];
-export type MiniProgramPermissionKey = (typeof MINI_PROGRAM_PERMISSION_KEYS)[number];
-export type MiniProgramPermissionRequirement = {
-    readonly kind: 'none';
-} | {
-    readonly kind: 'all';
-    readonly permissions: readonly MiniProgramPermissionKey[];
-};
-export type MiniProgramPermissionAccess = 'declaration' | 'platform-approval';
-export interface MiniProgramPermissionConfigFieldDefinition {
-    readonly type: 'boolean';
-    readonly required: boolean;
-    readonly default: boolean;
-    readonly description: string;
-}
-export interface MiniProgramPermissionDefinition {
-    readonly key: MiniProgramPermissionKey;
-    readonly name: string;
-    readonly description: string;
-    readonly access: MiniProgramPermissionAccess;
-    readonly risk: MiniProgramCapabilityRisk;
-    readonly config: Readonly<Record<string, MiniProgramPermissionConfigFieldDefinition>>;
-    readonly methods: readonly MiniProgramBridgeMethod[];
-    readonly conditions: readonly string[];
-}
-export declare const MINI_PROGRAM_PERMISSION_CATALOG: readonly [{
-    readonly key: "userInfo";
-    readonly name: "用户信息";
-    readonly description: "登录小程序并读取当前用户的授权信息。";
-    readonly access: "declaration";
-    readonly risk: "medium";
-    readonly config: {};
-    readonly methods: readonly ["auth.login", "user.getInfo"];
-    readonly conditions: readonly ["继续执行黑盒登录、用户授权和可信手势规则。"];
-}, {
-    readonly key: "steamLibrary";
-    readonly name: "Steam 游戏库";
-    readonly description: "读取当前用户授权的 Steam 游戏库。";
-    readonly access: "declaration";
-    readonly risk: "high";
-    readonly config: {};
-    readonly methods: readonly ["user.getSteamGameList"];
-    readonly conditions: readonly ["继续执行账号绑定和数据可用性规则。"];
-}, {
-    readonly key: "share";
-    readonly name: "分享";
-    readonly description: "使用小程序分享、分享菜单和截图能力。";
-    readonly access: "declaration";
-    readonly risk: "medium";
-    readonly config: {};
-    readonly methods: readonly ["share.copyLink", "share.showShareMenu", "share.screenshot"];
-    readonly conditions: readonly ["继续执行分享参数校验和 Host 支持检查。"];
-}, {
-    readonly key: "storage";
-    readonly name: "键值存储";
-    readonly description: "读写按小程序隔离的简单键值数据。";
-    readonly access: "declaration";
-    readonly risk: "medium";
-    readonly config: {};
-    readonly methods: readonly ["storage.getStorage", "storage.setStorage"];
-    readonly conditions: readonly ["仅用于简单键值存储，不包含文件系统。"];
-}, {
-    readonly key: "filesystem";
-    readonly name: "文件系统";
-    readonly description: "访问小程序沙盒文件和用户选择的外部文件。";
-    readonly access: "declaration";
-    readonly risk: "high";
-    readonly config: {};
-    readonly methods: readonly ["network.download", "files.pickFiles", "files.pickDirectory", "files.saveFile", "file.create", "file.remove", "file.exists", "file.readText", "file.writeText", "file.readBytes", "file.writeBytes", "file.stat", "directory.create", "directory.remove", "directory.exists", "directory.list"];
-    readonly conditions: readonly ["外部文件继续要求有效的用户选择、会话句柄和匹配的读写模式。"];
-}, {
-    readonly key: "clipboard";
-    readonly name: "剪贴板";
-    readonly description: "向系统剪贴板写入文本。";
-    readonly access: "declaration";
-    readonly risk: "medium";
-    readonly config: {};
-    readonly methods: readonly ["device.setClipboard"];
-    readonly conditions: readonly ["继续执行文本长度和 Host 支持限制。"];
-}, {
-    readonly key: "leaderboard";
-    readonly name: "排行榜";
-    readonly description: "读写小程序云排行榜。";
-    readonly access: "declaration";
-    readonly risk: "medium";
-    readonly config: {};
-    readonly methods: readonly ["cloud.leaderboard.submit", "cloud.leaderboard.getList", "cloud.leaderboard.getCurrentUserEntry", "cloud.leaderboard.deleteCurrentUserEntry", "cloud.leaderboard.getInfo"];
-    readonly conditions: readonly ["排行榜必须已创建，用户和资源规则保持不变。"];
-}, {
-    readonly key: "network";
-    readonly name: "网络";
-    readonly description: "通过 network 模块请求或下载外部资源。";
-    readonly access: "platform-approval";
-    readonly risk: "high";
-    readonly config: {
-        readonly useOfficialDomain: {
-            readonly type: "boolean";
-            readonly required: false;
-            readonly default: false;
-            readonly description: "是否申请访问小黑盒官方域名。";
-        };
-    };
-    readonly methods: readonly ["network.request", "network.download"];
-    readonly conditions: readonly ["声明后仍需平台批准，并继续执行网络安全策略。"];
-}, {
-    readonly key: "companion";
-    readonly name: "桌面辅助应用";
-    readonly description: "下载、准备并运行随当前小程序版本发布的受管桌面程序。";
-    readonly access: "platform-approval";
-    readonly risk: "high";
-    readonly config: {};
-    readonly methods: readonly ["companion.getInfo", "companion.getPreparationStatus", "companion.prepare", "companion.cancelPreparation", "companion.getActiveSession", "companion.launch", "companion.session.write", "companion.session.closeStdin", "companion.session.terminate", "companion.session.ackOutput", "companion.openAttachment", "companion.showNotification"];
-    readonly conditions: readonly ["声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。"];
-}];
-export declare const MINI_PROGRAM_NO_DECLARATION_METHODS: readonly ["user.revokeAuthorization", "ui.showToast", "ui.showLoading", "ui.hideLoading", "viewport.getWindowInfo", "viewport.setNavigationBarStyle", "viewport.setDisplay", "device.vibrate", "navigation.close", "navigation.reload", "navigation.openAppPage"];
-export declare function isMiniProgramPermissionKey(key: string): key is MiniProgramPermissionKey;

package/types/permissions.d.ts

@@ -1,159 +0,0 @@
-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 {
-    key: MiniProgramPermissionKey;
-    status: MiniProgramRuntimePermissionStatus;
-    config: Record<string, unknown>;
-}
-export interface MiniProgramRuntimePermissionsSnapshot {
-    schema_version: 1;
-    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;