@heybox/hb-sdk-protocol 0.8.1-alpha.3 → 0.8.1-alpha.7

package/README.md

@@ -1,5 +1,7 @@
 # @heybox/hb-sdk-protocol
 
+目录引用的 `relativePath` 允许完整 `.` 表示当前根；普通相对路径及文件引用仍拒绝点段、父目录和绝对路径。
+
 小黑盒外部小程序 SDK 与宿主 Runtime 共用的零依赖 wire contract。它只描述跨 iframe 边界传输的数据和校验规则，不执行 bridge、网络、登录、存储或任何平台能力。
 
 ## 边界
@@ -39,7 +41,11 @@ import { MINI_PROGRAM_PROTOCOL_CAPABILITIES, type MiniProgramBridgeMessage } fro
 
 ## 权限快照
 
-`MINI_PROGRAM_PERMISSION_CATALOG` 定义 8 个公开权限，`MINI_PROGRAM_PROTOCOL_CAPABILITIES[].requirement` 将每个 bridge method 显式分类为无需声明或要求全部列出的权限。`parseMiniProgramRuntimePermissions()` 是 schema v1 的 fail-closed 解析器；旧 `network.request` entry 仅在解析边界归一为 `network`，不得进入新配置。跨语言目录由 `generated/permission-catalog.json` 提供。
+`MINI_PROGRAM_PERMISSION_CATALOG` 定义 9 个公开权限，`MINI_PROGRAM_PROTOCOL_CAPABILITIES[].requirement` 将每个 bridge method 显式分类为无需声明或要求全部列出的权限。`companion` 是无配置项的高风险平台审批权限，覆盖准备、启动、活动 Session 控制、stdio、附件与通知 wire method。`parseMiniProgramRuntimePermissions()` 是 schema v1 的 fail-closed 解析器；旧 `network.request` entry 仅在解析边界归一为 `network`，不得进入新配置。未知权限 entry 会被忽略，即使 `config` 为 `null` 或缺失，也不能让已认识的批准失效。跨语言目录由 `generated/permission-catalog.json` 提供。
+
+耗时能力通过 `MiniProgramCapabilityProgressMap` 按 method 绑定进度 payload；当前覆盖 `network.download` 与 `companion.prepare`。Companion Session wire 只携带不透明 Session ID、controller generation、原始字节 chunk/ack、exit 和 ownership-lost 事件，不暴露 PID、路径或原生句柄。
+
+`CompanionInfo.source` 由可信 Host 标识 `local-dev` 或 `released`，与 `signatureStatus` 一起供授权展示使用；旧 Host 未提供来源时保持未知，不能推定为已审核产物。
 
 协议包不决定业务授权。`auth.login()` 的 UI、账号会话、授权码签发和 OpenAPI 都由 Host/服务端负责；协议层只传递经过约束的 request/response 数据。
 

package/dist/index.cjs.js

@@ -1,5 +1,17 @@
 'use strict';
 
+const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+const MINI_PROGRAM_MESSAGE_VERSION = 2;
+const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
+const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
+const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe';
+const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report';
+const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation';
+const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress';
+const COMPANION_SESSION_OUTPUT_EVENT = 'companion.session.output';
+const COMPANION_SESSION_EXIT_EVENT = 'companion.session.exit';
+const COMPANION_SESSION_OWNERSHIP_LOST_EVENT = 'companion.session.ownershipLost';
+
 const AUTH_LOGIN_METHOD = 'auth.login';
 const USER_GET_INFO_METHOD = 'user.getInfo';
 const USER_REVOKE_AUTHORIZATION_METHOD = 'user.revokeAuthorization';
@@ -41,6 +53,18 @@ const CLOUD_LEADERBOARD_GET_LIST_METHOD = 'cloud.leaderboard.getList';
 const CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.getCurrentUserEntry';
 const CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.deleteCurrentUserEntry';
 const CLOUD_LEADERBOARD_GET_INFO_METHOD = 'cloud.leaderboard.getInfo';
+const COMPANION_GET_INFO_METHOD = 'companion.getInfo';
+const COMPANION_GET_PREPARATION_STATUS_METHOD = 'companion.getPreparationStatus';
+const COMPANION_PREPARE_METHOD = 'companion.prepare';
+const COMPANION_CANCEL_PREPARATION_METHOD = 'companion.cancelPreparation';
+const COMPANION_GET_ACTIVE_SESSION_METHOD = 'companion.getActiveSession';
+const COMPANION_LAUNCH_METHOD = 'companion.launch';
+const COMPANION_SESSION_WRITE_METHOD = 'companion.session.write';
+const COMPANION_SESSION_CLOSE_STDIN_METHOD = 'companion.session.closeStdin';
+const COMPANION_SESSION_TERMINATE_METHOD = 'companion.session.terminate';
+const COMPANION_SESSION_ACK_OUTPUT_METHOD = 'companion.session.ackOutput';
+const COMPANION_OPEN_ATTACHMENT_METHOD = 'companion.openAttachment';
+const COMPANION_SHOW_NOTIFICATION_METHOD = 'companion.showNotification';
 const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
     {
         method: AUTH_LOGIN_METHOD,
@@ -287,17 +311,28 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
         requirement: { kind: 'all', permissions: ['leaderboard'] },
         risk: 'low',
     },
+    ...[
+        COMPANION_GET_INFO_METHOD,
+        COMPANION_GET_PREPARATION_STATUS_METHOD,
+        COMPANION_PREPARE_METHOD,
+        COMPANION_CANCEL_PREPARATION_METHOD,
+        COMPANION_GET_ACTIVE_SESSION_METHOD,
+        COMPANION_LAUNCH_METHOD,
+        COMPANION_SESSION_WRITE_METHOD,
+        COMPANION_SESSION_CLOSE_STDIN_METHOD,
+        COMPANION_SESSION_TERMINATE_METHOD,
+        COMPANION_SESSION_ACK_OUTPUT_METHOD,
+        COMPANION_OPEN_ATTACHMENT_METHOD,
+        COMPANION_SHOW_NOTIFICATION_METHOD,
+    ].map((method) => ({
+        method,
+        module: 'companion',
+        capability: method,
+        requirement: { kind: 'all', permissions: ['companion'] },
+        risk: 'high',
+    })),
 ];
 
-const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
-const MINI_PROGRAM_MESSAGE_VERSION = 2;
-const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
-const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
-const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe';
-const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report';
-const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation';
-const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress';
-
 function isMiniProgramBridgeMessage(value) {
     if (!isRecord$1(value))
         return false;
@@ -319,7 +354,7 @@ function isMiniProgramBridgeMessage(value) {
         if (!isNonEmptyString(value.method) || value.error !== undefined)
             return false;
         if (value.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
-            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramDownloadProgressPayload(value.payload);
+            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramOperationProgressPayload(value.payload);
         }
         return value.id === undefined || isNonEmptyString(value.id);
     }
@@ -357,7 +392,7 @@ function isMiniProgramDirectoryRef(value) {
     if (isNonEmptyString(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
     }
-    return (isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
+    return (isMiniProgramPathRootRef(value.root) && (value.relativePath === '.' || isMiniProgramRelativePath(value.relativePath)) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
 function isMiniProgramFileDescriptor(value) {
     return (isRecord$1(value) &&
@@ -400,6 +435,24 @@ function isMiniProgramDownloadProgressPayload(value) {
         return value.total === undefined;
     return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
 }
+function isMiniProgramCompanionPrepareProgress(value) {
+    if (!isRecord$1(value))
+        return false;
+    if (value.phase === 'downloading') {
+        return (isNonNegativeSafeInteger(value.loaded) &&
+            (value.total === undefined || (isNonNegativeSafeInteger(value.total) && value.loaded <= value.total)) &&
+            hasOnlyKeys(value, ['phase', 'loaded', 'total']));
+    }
+    if (value.phase !== 'verifying' && value.phase !== 'extracting')
+        return false;
+    return (isNonNegativeSafeInteger(value.processed) &&
+        isNonNegativeSafeInteger(value.total) &&
+        value.processed <= value.total &&
+        hasOnlyKeys(value, ['phase', 'processed', 'total']));
+}
+function isMiniProgramOperationProgressPayload(value) {
+    return isMiniProgramDownloadProgressPayload(value) || isMiniProgramCompanionPrepareProgress(value);
+}
 function isSDKHandshakePayload(value) {
     return isRecord$1(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
 }
@@ -428,6 +481,34 @@ function isRecord$1(value) {
 
 /** 当前用户信息与登录能力支持的完整 scope 目录。 */
 const USER_INFO_AUTHORIZATION_SCOPES = ['identity', 'profile'];
+/** Companion alias 的跨构建、Runtime 与 Host 规范。 */
+const COMPANION_ALIAS_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+/** Companion Host 可跨 bridge 保留的稳定领域错误码。 */
+const COMPANION_ERROR_CODES = [
+    'COMPANION_UNSUPPORTED',
+    'COMPANION_NOT_DECLARED',
+    'COMPANION_TARGET_UNSUPPORTED',
+    'COMPANION_NOT_PREPARED',
+    'COMPANION_PREPARATION_CANCELLED',
+    'COMPANION_DOWNLOAD_FAILED',
+    'COMPANION_DESCRIPTOR_UNAVAILABLE',
+    'COMPANION_ARCHIVE_INVALID',
+    'COMPANION_INTEGRITY_FAILED',
+    'COMPANION_ENTRYPOINT_INVALID',
+    'COMPANION_USER_CANCELLED',
+    'COMPANION_ELEVATION_DENIED',
+    'COMPANION_OS_BLOCKED',
+    'COMPANION_LAUNCH_FAILED',
+    'COMPANION_SESSION_VERSION_MISMATCH',
+    'COMPANION_SESSION_OWNERSHIP_LOST',
+    'COMPANION_SESSION_EXITED',
+    'COMPANION_PIPE_CLOSED',
+    'COMPANION_OUTPUT_LIMIT',
+    'COMPANION_PROCESS_CRASHED',
+    'COMPANION_ATTACHMENT_NOT_FOUND',
+    'COMPANION_NOTIFICATION_UNAVAILABLE',
+    'COMPANION_TERMINATE_FAILED',
+];
 
 const MINI_PROGRAM_PERMISSION_KEYS = [
     'userInfo',
@@ -438,6 +519,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'clipboard',
     'leaderboard',
     'network',
+    'companion',
 ];
 const MINI_PROGRAM_PERMISSION_CATALOG = [
     {
@@ -550,6 +632,29 @@ const MINI_PROGRAM_PERMISSION_CATALOG = [
         methods: ['network.request', 'network.download'],
         conditions: ['声明后仍需平台批准，并继续执行网络安全策略。'],
     },
+    {
+        key: 'companion',
+        name: '桌面辅助应用',
+        description: '下载、准备并运行随当前小程序版本发布的受管桌面程序。',
+        access: 'platform-approval',
+        risk: 'high',
+        config: {},
+        methods: [
+            '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',
+        ],
+        conditions: ['声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。'],
+    },
 ];
 const MINI_PROGRAM_NO_DECLARATION_METHODS = [
     'user.revokeAuthorization',
@@ -592,8 +697,8 @@ function parseMiniProgramRuntimePermissions(snapshot) {
         }
         seenKeys.add(key);
         if (!isManagedMiniProgramRuntimePermissionKey(key)) {
-            if (!isRecord(rawEntry.config))
-                return { valid: false, permissions: {} };
+            // 未知权限必须忽略，不能让 config:null / 缺字段把已认识的批准一起否掉。
+            // 服务端会对无 config 的 message 字段输出 null（Rylai EmitUnpopulated）。
             continue;
         }
         if (key === 'network') {
@@ -629,6 +734,23 @@ exports.CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD = CLOUD_LEADERBOARD_GET_
 exports.CLOUD_LEADERBOARD_GET_INFO_METHOD = CLOUD_LEADERBOARD_GET_INFO_METHOD;
 exports.CLOUD_LEADERBOARD_GET_LIST_METHOD = CLOUD_LEADERBOARD_GET_LIST_METHOD;
 exports.CLOUD_LEADERBOARD_SUBMIT_METHOD = CLOUD_LEADERBOARD_SUBMIT_METHOD;
+exports.COMPANION_ALIAS_PATTERN = COMPANION_ALIAS_PATTERN;
+exports.COMPANION_CANCEL_PREPARATION_METHOD = COMPANION_CANCEL_PREPARATION_METHOD;
+exports.COMPANION_ERROR_CODES = COMPANION_ERROR_CODES;
+exports.COMPANION_GET_ACTIVE_SESSION_METHOD = COMPANION_GET_ACTIVE_SESSION_METHOD;
+exports.COMPANION_GET_INFO_METHOD = COMPANION_GET_INFO_METHOD;
+exports.COMPANION_GET_PREPARATION_STATUS_METHOD = COMPANION_GET_PREPARATION_STATUS_METHOD;
+exports.COMPANION_LAUNCH_METHOD = COMPANION_LAUNCH_METHOD;
+exports.COMPANION_OPEN_ATTACHMENT_METHOD = COMPANION_OPEN_ATTACHMENT_METHOD;
+exports.COMPANION_PREPARE_METHOD = COMPANION_PREPARE_METHOD;
+exports.COMPANION_SESSION_ACK_OUTPUT_METHOD = COMPANION_SESSION_ACK_OUTPUT_METHOD;
+exports.COMPANION_SESSION_CLOSE_STDIN_METHOD = COMPANION_SESSION_CLOSE_STDIN_METHOD;
+exports.COMPANION_SESSION_EXIT_EVENT = COMPANION_SESSION_EXIT_EVENT;
+exports.COMPANION_SESSION_OUTPUT_EVENT = COMPANION_SESSION_OUTPUT_EVENT;
+exports.COMPANION_SESSION_OWNERSHIP_LOST_EVENT = COMPANION_SESSION_OWNERSHIP_LOST_EVENT;
+exports.COMPANION_SESSION_TERMINATE_METHOD = COMPANION_SESSION_TERMINATE_METHOD;
+exports.COMPANION_SESSION_WRITE_METHOD = COMPANION_SESSION_WRITE_METHOD;
+exports.COMPANION_SHOW_NOTIFICATION_METHOD = COMPANION_SHOW_NOTIFICATION_METHOD;
 exports.DEVICE_SET_CLIPBOARD_METHOD = DEVICE_SET_CLIPBOARD_METHOD;
 exports.DEVICE_VIBRATE_METHOD = DEVICE_VIBRATE_METHOD;
 exports.DIRECTORY_CREATE_METHOD = DIRECTORY_CREATE_METHOD;
@@ -680,6 +802,7 @@ exports.VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = VIEWPORT_SET_NAVIGATION_BAR_S
 exports.isManagedMiniProgramRuntimePermissionKey = isManagedMiniProgramRuntimePermissionKey;
 exports.isMiniProgramBridgeMessage = isMiniProgramBridgeMessage;
 exports.isMiniProgramByteArray = isMiniProgramByteArray;
+exports.isMiniProgramCompanionPrepareProgress = isMiniProgramCompanionPrepareProgress;
 exports.isMiniProgramDirectoryDescriptor = isMiniProgramDirectoryDescriptor;
 exports.isMiniProgramDirectoryRef = isMiniProgramDirectoryRef;
 exports.isMiniProgramDownloadProgressPayload = isMiniProgramDownloadProgressPayload;
@@ -687,6 +810,7 @@ exports.isMiniProgramFileDescriptor = isMiniProgramFileDescriptor;
 exports.isMiniProgramFileRef = isMiniProgramFileRef;
 exports.isMiniProgramFileStat = isMiniProgramFileStat;
 exports.isMiniProgramFileSystemEntityDescriptor = isMiniProgramFileSystemEntityDescriptor;
+exports.isMiniProgramOperationProgressPayload = isMiniProgramOperationProgressPayload;
 exports.isMiniProgramPathRootRef = isMiniProgramPathRootRef;
 exports.isMiniProgramPermissionKey = isMiniProgramPermissionKey;
 exports.isMiniProgramRelativePath = isMiniProgramRelativePath;

package/dist/index.esm.js

@@ -1,3 +1,15 @@
+const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+const MINI_PROGRAM_MESSAGE_VERSION = 2;
+const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
+const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
+const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe';
+const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report';
+const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation';
+const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress';
+const COMPANION_SESSION_OUTPUT_EVENT = 'companion.session.output';
+const COMPANION_SESSION_EXIT_EVENT = 'companion.session.exit';
+const COMPANION_SESSION_OWNERSHIP_LOST_EVENT = 'companion.session.ownershipLost';
+
 const AUTH_LOGIN_METHOD = 'auth.login';
 const USER_GET_INFO_METHOD = 'user.getInfo';
 const USER_REVOKE_AUTHORIZATION_METHOD = 'user.revokeAuthorization';
@@ -39,6 +51,18 @@ const CLOUD_LEADERBOARD_GET_LIST_METHOD = 'cloud.leaderboard.getList';
 const CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.getCurrentUserEntry';
 const CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD = 'cloud.leaderboard.deleteCurrentUserEntry';
 const CLOUD_LEADERBOARD_GET_INFO_METHOD = 'cloud.leaderboard.getInfo';
+const COMPANION_GET_INFO_METHOD = 'companion.getInfo';
+const COMPANION_GET_PREPARATION_STATUS_METHOD = 'companion.getPreparationStatus';
+const COMPANION_PREPARE_METHOD = 'companion.prepare';
+const COMPANION_CANCEL_PREPARATION_METHOD = 'companion.cancelPreparation';
+const COMPANION_GET_ACTIVE_SESSION_METHOD = 'companion.getActiveSession';
+const COMPANION_LAUNCH_METHOD = 'companion.launch';
+const COMPANION_SESSION_WRITE_METHOD = 'companion.session.write';
+const COMPANION_SESSION_CLOSE_STDIN_METHOD = 'companion.session.closeStdin';
+const COMPANION_SESSION_TERMINATE_METHOD = 'companion.session.terminate';
+const COMPANION_SESSION_ACK_OUTPUT_METHOD = 'companion.session.ackOutput';
+const COMPANION_OPEN_ATTACHMENT_METHOD = 'companion.openAttachment';
+const COMPANION_SHOW_NOTIFICATION_METHOD = 'companion.showNotification';
 const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
     {
         method: AUTH_LOGIN_METHOD,
@@ -285,17 +309,28 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
         requirement: { kind: 'all', permissions: ['leaderboard'] },
         risk: 'low',
     },
+    ...[
+        COMPANION_GET_INFO_METHOD,
+        COMPANION_GET_PREPARATION_STATUS_METHOD,
+        COMPANION_PREPARE_METHOD,
+        COMPANION_CANCEL_PREPARATION_METHOD,
+        COMPANION_GET_ACTIVE_SESSION_METHOD,
+        COMPANION_LAUNCH_METHOD,
+        COMPANION_SESSION_WRITE_METHOD,
+        COMPANION_SESSION_CLOSE_STDIN_METHOD,
+        COMPANION_SESSION_TERMINATE_METHOD,
+        COMPANION_SESSION_ACK_OUTPUT_METHOD,
+        COMPANION_OPEN_ATTACHMENT_METHOD,
+        COMPANION_SHOW_NOTIFICATION_METHOD,
+    ].map((method) => ({
+        method,
+        module: 'companion',
+        capability: method,
+        requirement: { kind: 'all', permissions: ['companion'] },
+        risk: 'high',
+    })),
 ];
 
-const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
-const MINI_PROGRAM_MESSAGE_VERSION = 2;
-const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
-const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
-const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe';
-const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report';
-const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation';
-const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress';
-
 function isMiniProgramBridgeMessage(value) {
     if (!isRecord$1(value))
         return false;
@@ -317,7 +352,7 @@ function isMiniProgramBridgeMessage(value) {
         if (!isNonEmptyString(value.method) || value.error !== undefined)
             return false;
         if (value.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
-            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramDownloadProgressPayload(value.payload);
+            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramOperationProgressPayload(value.payload);
         }
         return value.id === undefined || isNonEmptyString(value.id);
     }
@@ -355,7 +390,7 @@ function isMiniProgramDirectoryRef(value) {
     if (isNonEmptyString(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
     }
-    return (isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
+    return (isMiniProgramPathRootRef(value.root) && (value.relativePath === '.' || isMiniProgramRelativePath(value.relativePath)) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
 function isMiniProgramFileDescriptor(value) {
     return (isRecord$1(value) &&
@@ -398,6 +433,24 @@ function isMiniProgramDownloadProgressPayload(value) {
         return value.total === undefined;
     return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
 }
+function isMiniProgramCompanionPrepareProgress(value) {
+    if (!isRecord$1(value))
+        return false;
+    if (value.phase === 'downloading') {
+        return (isNonNegativeSafeInteger(value.loaded) &&
+            (value.total === undefined || (isNonNegativeSafeInteger(value.total) && value.loaded <= value.total)) &&
+            hasOnlyKeys(value, ['phase', 'loaded', 'total']));
+    }
+    if (value.phase !== 'verifying' && value.phase !== 'extracting')
+        return false;
+    return (isNonNegativeSafeInteger(value.processed) &&
+        isNonNegativeSafeInteger(value.total) &&
+        value.processed <= value.total &&
+        hasOnlyKeys(value, ['phase', 'processed', 'total']));
+}
+function isMiniProgramOperationProgressPayload(value) {
+    return isMiniProgramDownloadProgressPayload(value) || isMiniProgramCompanionPrepareProgress(value);
+}
 function isSDKHandshakePayload(value) {
     return isRecord$1(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
 }
@@ -426,6 +479,34 @@ function isRecord$1(value) {
 
 /** 当前用户信息与登录能力支持的完整 scope 目录。 */
 const USER_INFO_AUTHORIZATION_SCOPES = ['identity', 'profile'];
+/** Companion alias 的跨构建、Runtime 与 Host 规范。 */
+const COMPANION_ALIAS_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+/** Companion Host 可跨 bridge 保留的稳定领域错误码。 */
+const COMPANION_ERROR_CODES = [
+    'COMPANION_UNSUPPORTED',
+    'COMPANION_NOT_DECLARED',
+    'COMPANION_TARGET_UNSUPPORTED',
+    'COMPANION_NOT_PREPARED',
+    'COMPANION_PREPARATION_CANCELLED',
+    'COMPANION_DOWNLOAD_FAILED',
+    'COMPANION_DESCRIPTOR_UNAVAILABLE',
+    'COMPANION_ARCHIVE_INVALID',
+    'COMPANION_INTEGRITY_FAILED',
+    'COMPANION_ENTRYPOINT_INVALID',
+    'COMPANION_USER_CANCELLED',
+    'COMPANION_ELEVATION_DENIED',
+    'COMPANION_OS_BLOCKED',
+    'COMPANION_LAUNCH_FAILED',
+    'COMPANION_SESSION_VERSION_MISMATCH',
+    'COMPANION_SESSION_OWNERSHIP_LOST',
+    'COMPANION_SESSION_EXITED',
+    'COMPANION_PIPE_CLOSED',
+    'COMPANION_OUTPUT_LIMIT',
+    'COMPANION_PROCESS_CRASHED',
+    'COMPANION_ATTACHMENT_NOT_FOUND',
+    'COMPANION_NOTIFICATION_UNAVAILABLE',
+    'COMPANION_TERMINATE_FAILED',
+];
 
 const MINI_PROGRAM_PERMISSION_KEYS = [
     'userInfo',
@@ -436,6 +517,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'clipboard',
     'leaderboard',
     'network',
+    'companion',
 ];
 const MINI_PROGRAM_PERMISSION_CATALOG = [
     {
@@ -548,6 +630,29 @@ const MINI_PROGRAM_PERMISSION_CATALOG = [
         methods: ['network.request', 'network.download'],
         conditions: ['声明后仍需平台批准，并继续执行网络安全策略。'],
     },
+    {
+        key: 'companion',
+        name: '桌面辅助应用',
+        description: '下载、准备并运行随当前小程序版本发布的受管桌面程序。',
+        access: 'platform-approval',
+        risk: 'high',
+        config: {},
+        methods: [
+            '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',
+        ],
+        conditions: ['声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。'],
+    },
 ];
 const MINI_PROGRAM_NO_DECLARATION_METHODS = [
     'user.revokeAuthorization',
@@ -590,8 +695,8 @@ function parseMiniProgramRuntimePermissions(snapshot) {
         }
         seenKeys.add(key);
         if (!isManagedMiniProgramRuntimePermissionKey(key)) {
-            if (!isRecord(rawEntry.config))
-                return { valid: false, permissions: {} };
+            // 未知权限必须忽略，不能让 config:null / 缺字段把已认识的批准一起否掉。
+            // 服务端会对无 config 的 message 字段输出 null（Rylai EmitUnpopulated）。
             continue;
         }
         if (key === 'network') {
@@ -621,4 +726,4 @@ function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_NO_DECLARATION_METHODS, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PERMISSION_CATALOG, MINI_PROGRAM_PERMISSION_KEYS, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_DOWNLOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramPathRootRef, isMiniProgramPermissionKey, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions };
+export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, COMPANION_ALIAS_PATTERN, COMPANION_CANCEL_PREPARATION_METHOD, COMPANION_ERROR_CODES, COMPANION_GET_ACTIVE_SESSION_METHOD, COMPANION_GET_INFO_METHOD, COMPANION_GET_PREPARATION_STATUS_METHOD, COMPANION_LAUNCH_METHOD, COMPANION_OPEN_ATTACHMENT_METHOD, COMPANION_PREPARE_METHOD, COMPANION_SESSION_ACK_OUTPUT_METHOD, COMPANION_SESSION_CLOSE_STDIN_METHOD, COMPANION_SESSION_EXIT_EVENT, COMPANION_SESSION_OUTPUT_EVENT, COMPANION_SESSION_OWNERSHIP_LOST_EVENT, COMPANION_SESSION_TERMINATE_METHOD, COMPANION_SESSION_WRITE_METHOD, COMPANION_SHOW_NOTIFICATION_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_NO_DECLARATION_METHODS, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PERMISSION_CATALOG, MINI_PROGRAM_PERMISSION_KEYS, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_DOWNLOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramCompanionPrepareProgress, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramOperationProgressPayload, isMiniProgramPathRootRef, isMiniProgramPermissionKey, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk-protocol",
-  "version": "0.8.1-alpha.3",
+  "version": "0.8.1-alpha.7",
   "description": "Heybox mini-program iframe bridge wire contracts.",
   "sideEffects": false,
   "exports": {

package/src/bridge.ts

@@ -1,5 +1,19 @@
-import { MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_OPERATION_PROGRESS_METHOD } from './constants';
-import type { DownloadProgressPayload, MiniProgramRuntimeEnvironmentInfo, UserInfoAuthorization } from './payloads';
+import {
+  COMPANION_SESSION_EXIT_EVENT,
+  COMPANION_SESSION_OUTPUT_EVENT,
+  COMPANION_SESSION_OWNERSHIP_LOST_EVENT,
+  MINI_PROGRAM_MESSAGE_NAMESPACE,
+  MINI_PROGRAM_OPERATION_PROGRESS_METHOD,
+} from './constants';
+import type {
+  CompanionSessionExitPayload,
+  CompanionSessionOutputPayload,
+  CompanionSessionOwnershipLostPayload,
+  DownloadProgressPayload,
+  MiniProgramRuntimeEnvironmentInfo,
+  UserInfoAuthorization,
+} from './payloads';
+import type { MiniProgramCapabilityProgress, MiniProgramProgressMethod } from './capabilities';
 
 export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event' | 'cancel';
 export type MiniProgramEventName =
@@ -10,7 +24,10 @@ export type MiniProgramEventName =
   | 'unload'
   | 'error'
   | 'heybox_app_login_change'
-  | 'user_info_authorization_change';
+  | 'user_info_authorization_change'
+  | typeof COMPANION_SESSION_OUTPUT_EVENT
+  | typeof COMPANION_SESSION_EXIT_EVENT
+  | typeof COMPANION_SESSION_OWNERSHIP_LOST_EVENT;
 
 export interface MiniProgramBridgeError {
   code: string;
@@ -71,12 +88,14 @@ export interface MiniProgramBridgeCancelMessage extends MiniProgramBridgeMessage
   error?: never;
 }
 
-export interface MiniProgramBridgeProgressMessage extends MiniProgramBridgeMessage<DownloadProgressPayload> {
+export interface MiniProgramBridgeProgressMessage<
+  TMethod extends MiniProgramProgressMethod = MiniProgramProgressMethod,
+> extends MiniProgramBridgeMessage<MiniProgramCapabilityProgress<TMethod>> {
   version: 2;
   type: 'event';
   id: string;
   method: typeof MINI_PROGRAM_OPERATION_PROGRESS_METHOD;
-  payload: DownloadProgressPayload;
+  payload: MiniProgramCapabilityProgress<TMethod>;
   error?: never;
 }
 export interface MiniProgramEventPayloadMap {
@@ -88,4 +107,7 @@ export interface MiniProgramEventPayloadMap {
   error: MiniProgramBridgeError;
   heybox_app_login_change: { isHeyboxAppLoggedIn: boolean };
   user_info_authorization_change: UserInfoAuthorization;
+  [COMPANION_SESSION_OUTPUT_EVENT]: CompanionSessionOutputPayload;
+  [COMPANION_SESSION_EXIT_EVENT]: CompanionSessionExitPayload;
+  [COMPANION_SESSION_OWNERSHIP_LOST_EVENT]: CompanionSessionOwnershipLostPayload;
 }