@heybox/hb-sdk-protocol 0.7.4-alpha.1

package/README.md

@@ -0,0 +1,62 @@
+# @heybox/hb-sdk-protocol
+
+小黑盒外部小程序 SDK 与宿主 Runtime 共用的零依赖 wire contract。它只描述跨 iframe 边界传输的数据和校验规则，不执行 bridge、网络、登录、存储或任何平台能力。
+
+## 边界
+
+`@heybox/hb-sdk-protocol` 拥有：
+
+- bridge namespace、协议版本、method 常量和事件名称；
+- capability metadata（module、capability、permission、risk）；
+- method payload/result 与错误的 wire 类型；
+- `runtime_permissions` schema 解析器和相关类型。
+
+它不拥有：
+
+- `@heybox/hb-sdk` 的客户端状态机或默认单例；
+- `@heybox/hb-sdk-runtime` 的 iframe、Host Port、Capability Module 或 Web Host；
+- HTTP 请求、凭据、Cookie、登录 UI、业务 API 或客户端原生协议；
+- DOM、Node.js、Electron 或任一具体平台实现。
+
+依赖方向固定为：
+
+```text
+@heybox/hb-sdk-protocol  <-  @heybox/hb-sdk
+@heybox/hb-sdk-protocol  <-  @heybox/hb-sdk-runtime
+```
+
+协议包不得反向依赖 SDK、Runtime 或应用。三包版本按 release family 锁步发布，顺序为 protocol -> Runtime -> SDK。
+
+## 使用方式
+
+宿主/Runtime 维护代码直接使用协议包：
+
+```ts
+import {
+  MINI_PROGRAM_PROTOCOL_CAPABILITIES,
+  type MiniProgramBridgeMessage,
+} from '@heybox/hb-sdk-protocol';
+```
+
+小程序业务代码不应导入该包；业务只使用 `@heybox/hb-sdk`。为了兼容已有 Host/Runtime 消费者，`@heybox/hb-sdk/protocol` 继续 re-export 本包的公开值和类型，但协议 owner 是本包。
+
+## 权限快照
+
+`parseMiniProgramRuntimePermissions()` 是唯一的 schema v1 fail-closed 解析器。它校验 schema、entry 唯一性、managed key 和状态；未知但结构合法的新 key 会被保留/忽略，不会让当前版本误放行能力。Runtime 再使用 `hasMiniProgramNetworkRequestPermission()` 判断 `network.request` 是否明确启用。
+
+协议包不决定业务授权。`auth.login()` 的 UI、账号会话、授权码签发和 OpenAPI 都由 Host/服务端负责；协议层只传递经过约束的 request/response 数据。
+
+## 公开入口
+
+- `@heybox/hb-sdk-protocol`：本包唯一入口，适合 Host、Runtime 和协议维护代码。
+- `@heybox/hb-sdk/protocol`：SDK 的兼容入口，适合既有消费者；不应作为新的 contract owner。
+
+完整符号以源码导出和生成的 TypeScript declarations 为准。Runtime 集成见 [`@heybox/hb-sdk-runtime`](../hb-sdk-runtime/README.md)，客户端能力见 [`@heybox/hb-sdk`](../hb-sdk/README.md)。
+
+## 验证
+
+```bash
+pnpm --filter @heybox/hb-sdk-protocol run check:boundary
+pnpm --filter @heybox/hb-sdk-protocol run test:unit
+pnpm --filter @heybox/hb-sdk-protocol run build:package
+```

package/dist/index.cjs.js

@@ -0,0 +1,215 @@
+'use strict';
+
+const AUTH_LOGIN_METHOD = 'auth.login';
+const USER_GET_INFO_METHOD = 'user.getInfo';
+const USER_REVOKE_AUTHORIZATION_METHOD = 'user.revokeAuthorization';
+const USER_GET_STEAM_GAME_LIST_METHOD = 'user.getSteamGameList';
+const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
+const SHARE_SCREENSHOT_METHOD = 'share.screenshot';
+const VIEWPORT_GET_WINDOW_INFO_METHOD = 'viewport.getWindowInfo';
+const VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = 'viewport.setNavigationBarStyle';
+const STORAGE_GET_STORAGE_METHOD = 'storage.getStorage';
+const STORAGE_SET_STORAGE_METHOD = 'storage.setStorage';
+const NETWORK_REQUEST_METHOD = 'network.request';
+const UI_SHOW_TOAST_METHOD = 'ui.showToast';
+const UI_SHOW_LOADING_METHOD = 'ui.showLoading';
+const UI_HIDE_LOADING_METHOD = 'ui.hideLoading';
+const DEVICE_VIBRATE_METHOD = 'device.vibrate';
+const DEVICE_SET_CLIPBOARD_METHOD = 'device.setClipboard';
+const NAVIGATION_CLOSE_METHOD = 'navigation.close';
+const NAVIGATION_RELOAD_METHOD = 'navigation.reload';
+const NAVIGATION_OPEN_APP_PAGE_METHOD = 'navigation.openAppPage';
+const CLOUD_LEADERBOARD_SUBMIT_METHOD = 'cloud.leaderboard.submit';
+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 MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
+    { method: AUTH_LOGIN_METHOD, module: 'auth', capability: AUTH_LOGIN_METHOD, permission: 'auth.login', risk: 'medium' },
+    { method: USER_GET_INFO_METHOD, module: 'user', capability: USER_GET_INFO_METHOD, permission: 'user.getInfo', risk: 'medium' },
+    {
+        method: USER_REVOKE_AUTHORIZATION_METHOD,
+        module: 'user',
+        capability: USER_REVOKE_AUTHORIZATION_METHOD,
+        permission: 'user.revokeAuthorization',
+        risk: 'high',
+    },
+    {
+        method: USER_GET_STEAM_GAME_LIST_METHOD,
+        module: 'user',
+        capability: USER_GET_STEAM_GAME_LIST_METHOD,
+        permission: 'user.platformAccount.steam',
+        risk: 'high',
+    },
+    { method: SHARE_SHOW_SHARE_MENU_METHOD, module: 'share', capability: SHARE_SHOW_SHARE_MENU_METHOD, permission: 'share.basic', risk: 'low' },
+    { method: SHARE_SCREENSHOT_METHOD, module: 'share', capability: SHARE_SCREENSHOT_METHOD, permission: 'share.screenshot', risk: 'medium' },
+    {
+        method: VIEWPORT_GET_WINDOW_INFO_METHOD,
+        module: 'viewport',
+        capability: VIEWPORT_GET_WINDOW_INFO_METHOD,
+        permission: 'viewport.windowInfo',
+        risk: 'low',
+    },
+    {
+        method: VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD,
+        module: 'viewport',
+        capability: VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD,
+        permission: 'viewport.navigationBarStyle',
+        risk: 'low',
+    },
+    { method: STORAGE_GET_STORAGE_METHOD, module: 'storage', capability: STORAGE_GET_STORAGE_METHOD, permission: 'storage.read', risk: 'low' },
+    { method: STORAGE_SET_STORAGE_METHOD, module: 'storage', capability: STORAGE_SET_STORAGE_METHOD, permission: 'storage.write', risk: 'medium' },
+    { method: NETWORK_REQUEST_METHOD, module: 'network', capability: NETWORK_REQUEST_METHOD, permission: 'network.request', risk: 'high' },
+    { method: UI_SHOW_TOAST_METHOD, module: 'ui', capability: UI_SHOW_TOAST_METHOD, permission: 'ui.toast', risk: 'low' },
+    { method: UI_SHOW_LOADING_METHOD, module: 'ui', capability: UI_SHOW_LOADING_METHOD, permission: 'ui.loading', risk: 'low' },
+    { method: UI_HIDE_LOADING_METHOD, module: 'ui', capability: UI_HIDE_LOADING_METHOD, permission: 'ui.loading', risk: 'low' },
+    { method: DEVICE_VIBRATE_METHOD, module: 'device', capability: DEVICE_VIBRATE_METHOD, permission: 'device.vibrate', risk: 'low' },
+    {
+        method: DEVICE_SET_CLIPBOARD_METHOD,
+        module: 'device',
+        capability: DEVICE_SET_CLIPBOARD_METHOD,
+        permission: 'device.clipboard.write',
+        risk: 'medium',
+    },
+    { method: NAVIGATION_CLOSE_METHOD, module: 'navigation', capability: NAVIGATION_CLOSE_METHOD, permission: 'navigation.close', risk: 'medium' },
+    { method: NAVIGATION_RELOAD_METHOD, module: 'navigation', capability: NAVIGATION_RELOAD_METHOD, permission: 'navigation.reload', risk: 'medium' },
+    {
+        method: NAVIGATION_OPEN_APP_PAGE_METHOD,
+        module: 'navigation',
+        capability: NAVIGATION_OPEN_APP_PAGE_METHOD,
+        permission: 'navigation.openAppPage',
+        risk: 'medium',
+    },
+    {
+        method: CLOUD_LEADERBOARD_SUBMIT_METHOD,
+        module: 'cloud',
+        capability: CLOUD_LEADERBOARD_SUBMIT_METHOD,
+        permission: 'cloud.leaderboard.write',
+        risk: 'medium',
+    },
+    {
+        method: CLOUD_LEADERBOARD_GET_LIST_METHOD,
+        module: 'cloud',
+        capability: CLOUD_LEADERBOARD_GET_LIST_METHOD,
+        permission: 'cloud.leaderboard.read',
+        risk: 'low',
+    },
+    {
+        method: CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD,
+        module: 'cloud',
+        capability: CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD,
+        permission: 'cloud.leaderboard.currentUserEntry.read',
+        risk: 'medium',
+    },
+    {
+        method: CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD,
+        module: 'cloud',
+        capability: CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD,
+        permission: 'cloud.leaderboard.currentUserEntry.delete',
+        risk: 'medium',
+    },
+    {
+        method: CLOUD_LEADERBOARD_GET_INFO_METHOD,
+        module: 'cloud',
+        capability: CLOUD_LEADERBOARD_GET_INFO_METHOD,
+        permission: 'cloud.leaderboard.info.read',
+        risk: 'low',
+    },
+];
+
+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';
+
+function isMiniProgramBridgeMessage(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const message = value;
+    return (message.namespace === MINI_PROGRAM_MESSAGE_NAMESPACE &&
+        (message.version === 1 || message.version === 2) &&
+        typeof message.nonce === 'string' &&
+        typeof message.type === 'string');
+}
+
+/** 当前用户信息与登录能力支持的完整 scope 目录。 */
+const USER_INFO_AUTHORIZATION_SCOPES = ['identity', 'profile'];
+
+const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(['network.request']);
+function isManagedMiniProgramRuntimePermissionKey(key) {
+    return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
+}
+function parseMiniProgramRuntimePermissions(snapshot) {
+    if (!isRecord(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
+        return { valid: false, permissions: {} };
+    }
+    if (snapshot.revision !== undefined && (typeof snapshot.revision !== 'number' || !Number.isInteger(snapshot.revision) || snapshot.revision < 0)) {
+        return { valid: false, permissions: {} };
+    }
+    const seenKeys = new Set();
+    const permissions = {};
+    for (const rawEntry of snapshot.entries) {
+        if (!isRecord(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
+            return { valid: false, permissions: {} };
+        }
+        const key = rawEntry.key.trim();
+        if (seenKeys.has(key) || (rawEntry.status !== 'enabled' && rawEntry.status !== 'disabled') || !isRecord(rawEntry.config)) {
+            return { valid: false, permissions: {} };
+        }
+        seenKeys.add(key);
+        if (!isManagedMiniProgramRuntimePermissionKey(key))
+            continue;
+        if (key === 'network.request' && typeof rawEntry.config.useOfficialDomain !== 'boolean') {
+            return { valid: false, permissions: {} };
+        }
+        permissions[key] = {
+            key,
+            status: rawEntry.status,
+            config: { useOfficialDomain: rawEntry.config.useOfficialDomain },
+        };
+    }
+    return { valid: true, permissions };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+exports.AUTH_LOGIN_METHOD = AUTH_LOGIN_METHOD;
+exports.CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD = CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD;
+exports.CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD = CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD;
+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.DEVICE_SET_CLIPBOARD_METHOD = DEVICE_SET_CLIPBOARD_METHOD;
+exports.DEVICE_VIBRATE_METHOD = DEVICE_VIBRATE_METHOD;
+exports.MINI_PROGRAM_BRIDGE_NONCE_PARAM = MINI_PROGRAM_BRIDGE_NONCE_PARAM;
+exports.MINI_PROGRAM_MESSAGE_NAMESPACE = MINI_PROGRAM_MESSAGE_NAMESPACE;
+exports.MINI_PROGRAM_MESSAGE_VERSION = MINI_PROGRAM_MESSAGE_VERSION;
+exports.MINI_PROGRAM_PROTOCOL_CAPABILITIES = MINI_PROGRAM_PROTOCOL_CAPABILITIES;
+exports.NAVIGATION_CLOSE_METHOD = NAVIGATION_CLOSE_METHOD;
+exports.NAVIGATION_OPEN_APP_PAGE_METHOD = NAVIGATION_OPEN_APP_PAGE_METHOD;
+exports.NAVIGATION_RELOAD_METHOD = NAVIGATION_RELOAD_METHOD;
+exports.NETWORK_REQUEST_METHOD = NETWORK_REQUEST_METHOD;
+exports.RUNTIME_LOCATION_PROBE_METHOD = RUNTIME_LOCATION_PROBE_METHOD;
+exports.SDK_CSP_VIOLATION_METHOD = SDK_CSP_VIOLATION_METHOD;
+exports.SDK_HANDSHAKE_METHOD = SDK_HANDSHAKE_METHOD;
+exports.SDK_LOCATION_REPORT_METHOD = SDK_LOCATION_REPORT_METHOD;
+exports.SHARE_SCREENSHOT_METHOD = SHARE_SCREENSHOT_METHOD;
+exports.SHARE_SHOW_SHARE_MENU_METHOD = SHARE_SHOW_SHARE_MENU_METHOD;
+exports.STORAGE_GET_STORAGE_METHOD = STORAGE_GET_STORAGE_METHOD;
+exports.STORAGE_SET_STORAGE_METHOD = STORAGE_SET_STORAGE_METHOD;
+exports.UI_HIDE_LOADING_METHOD = UI_HIDE_LOADING_METHOD;
+exports.UI_SHOW_LOADING_METHOD = UI_SHOW_LOADING_METHOD;
+exports.UI_SHOW_TOAST_METHOD = UI_SHOW_TOAST_METHOD;
+exports.USER_GET_INFO_METHOD = USER_GET_INFO_METHOD;
+exports.USER_GET_STEAM_GAME_LIST_METHOD = USER_GET_STEAM_GAME_LIST_METHOD;
+exports.USER_INFO_AUTHORIZATION_SCOPES = USER_INFO_AUTHORIZATION_SCOPES;
+exports.USER_REVOKE_AUTHORIZATION_METHOD = USER_REVOKE_AUTHORIZATION_METHOD;
+exports.VIEWPORT_GET_WINDOW_INFO_METHOD = VIEWPORT_GET_WINDOW_INFO_METHOD;
+exports.VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD;
+exports.isManagedMiniProgramRuntimePermissionKey = isManagedMiniProgramRuntimePermissionKey;
+exports.isMiniProgramBridgeMessage = isMiniProgramBridgeMessage;
+exports.parseMiniProgramRuntimePermissions = parseMiniProgramRuntimePermissions;

package/dist/index.esm.js

@@ -0,0 +1,178 @@
+const AUTH_LOGIN_METHOD = 'auth.login';
+const USER_GET_INFO_METHOD = 'user.getInfo';
+const USER_REVOKE_AUTHORIZATION_METHOD = 'user.revokeAuthorization';
+const USER_GET_STEAM_GAME_LIST_METHOD = 'user.getSteamGameList';
+const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
+const SHARE_SCREENSHOT_METHOD = 'share.screenshot';
+const VIEWPORT_GET_WINDOW_INFO_METHOD = 'viewport.getWindowInfo';
+const VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = 'viewport.setNavigationBarStyle';
+const STORAGE_GET_STORAGE_METHOD = 'storage.getStorage';
+const STORAGE_SET_STORAGE_METHOD = 'storage.setStorage';
+const NETWORK_REQUEST_METHOD = 'network.request';
+const UI_SHOW_TOAST_METHOD = 'ui.showToast';
+const UI_SHOW_LOADING_METHOD = 'ui.showLoading';
+const UI_HIDE_LOADING_METHOD = 'ui.hideLoading';
+const DEVICE_VIBRATE_METHOD = 'device.vibrate';
+const DEVICE_SET_CLIPBOARD_METHOD = 'device.setClipboard';
+const NAVIGATION_CLOSE_METHOD = 'navigation.close';
+const NAVIGATION_RELOAD_METHOD = 'navigation.reload';
+const NAVIGATION_OPEN_APP_PAGE_METHOD = 'navigation.openAppPage';
+const CLOUD_LEADERBOARD_SUBMIT_METHOD = 'cloud.leaderboard.submit';
+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 MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
+    { method: AUTH_LOGIN_METHOD, module: 'auth', capability: AUTH_LOGIN_METHOD, permission: 'auth.login', risk: 'medium' },
+    { method: USER_GET_INFO_METHOD, module: 'user', capability: USER_GET_INFO_METHOD, permission: 'user.getInfo', risk: 'medium' },
+    {
+        method: USER_REVOKE_AUTHORIZATION_METHOD,
+        module: 'user',
+        capability: USER_REVOKE_AUTHORIZATION_METHOD,
+        permission: 'user.revokeAuthorization',
+        risk: 'high',
+    },
+    {
+        method: USER_GET_STEAM_GAME_LIST_METHOD,
+        module: 'user',
+        capability: USER_GET_STEAM_GAME_LIST_METHOD,
+        permission: 'user.platformAccount.steam',
+        risk: 'high',
+    },
+    { method: SHARE_SHOW_SHARE_MENU_METHOD, module: 'share', capability: SHARE_SHOW_SHARE_MENU_METHOD, permission: 'share.basic', risk: 'low' },
+    { method: SHARE_SCREENSHOT_METHOD, module: 'share', capability: SHARE_SCREENSHOT_METHOD, permission: 'share.screenshot', risk: 'medium' },
+    {
+        method: VIEWPORT_GET_WINDOW_INFO_METHOD,
+        module: 'viewport',
+        capability: VIEWPORT_GET_WINDOW_INFO_METHOD,
+        permission: 'viewport.windowInfo',
+        risk: 'low',
+    },
+    {
+        method: VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD,
+        module: 'viewport',
+        capability: VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD,
+        permission: 'viewport.navigationBarStyle',
+        risk: 'low',
+    },
+    { method: STORAGE_GET_STORAGE_METHOD, module: 'storage', capability: STORAGE_GET_STORAGE_METHOD, permission: 'storage.read', risk: 'low' },
+    { method: STORAGE_SET_STORAGE_METHOD, module: 'storage', capability: STORAGE_SET_STORAGE_METHOD, permission: 'storage.write', risk: 'medium' },
+    { method: NETWORK_REQUEST_METHOD, module: 'network', capability: NETWORK_REQUEST_METHOD, permission: 'network.request', risk: 'high' },
+    { method: UI_SHOW_TOAST_METHOD, module: 'ui', capability: UI_SHOW_TOAST_METHOD, permission: 'ui.toast', risk: 'low' },
+    { method: UI_SHOW_LOADING_METHOD, module: 'ui', capability: UI_SHOW_LOADING_METHOD, permission: 'ui.loading', risk: 'low' },
+    { method: UI_HIDE_LOADING_METHOD, module: 'ui', capability: UI_HIDE_LOADING_METHOD, permission: 'ui.loading', risk: 'low' },
+    { method: DEVICE_VIBRATE_METHOD, module: 'device', capability: DEVICE_VIBRATE_METHOD, permission: 'device.vibrate', risk: 'low' },
+    {
+        method: DEVICE_SET_CLIPBOARD_METHOD,
+        module: 'device',
+        capability: DEVICE_SET_CLIPBOARD_METHOD,
+        permission: 'device.clipboard.write',
+        risk: 'medium',
+    },
+    { method: NAVIGATION_CLOSE_METHOD, module: 'navigation', capability: NAVIGATION_CLOSE_METHOD, permission: 'navigation.close', risk: 'medium' },
+    { method: NAVIGATION_RELOAD_METHOD, module: 'navigation', capability: NAVIGATION_RELOAD_METHOD, permission: 'navigation.reload', risk: 'medium' },
+    {
+        method: NAVIGATION_OPEN_APP_PAGE_METHOD,
+        module: 'navigation',
+        capability: NAVIGATION_OPEN_APP_PAGE_METHOD,
+        permission: 'navigation.openAppPage',
+        risk: 'medium',
+    },
+    {
+        method: CLOUD_LEADERBOARD_SUBMIT_METHOD,
+        module: 'cloud',
+        capability: CLOUD_LEADERBOARD_SUBMIT_METHOD,
+        permission: 'cloud.leaderboard.write',
+        risk: 'medium',
+    },
+    {
+        method: CLOUD_LEADERBOARD_GET_LIST_METHOD,
+        module: 'cloud',
+        capability: CLOUD_LEADERBOARD_GET_LIST_METHOD,
+        permission: 'cloud.leaderboard.read',
+        risk: 'low',
+    },
+    {
+        method: CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD,
+        module: 'cloud',
+        capability: CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD,
+        permission: 'cloud.leaderboard.currentUserEntry.read',
+        risk: 'medium',
+    },
+    {
+        method: CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD,
+        module: 'cloud',
+        capability: CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD,
+        permission: 'cloud.leaderboard.currentUserEntry.delete',
+        risk: 'medium',
+    },
+    {
+        method: CLOUD_LEADERBOARD_GET_INFO_METHOD,
+        module: 'cloud',
+        capability: CLOUD_LEADERBOARD_GET_INFO_METHOD,
+        permission: 'cloud.leaderboard.info.read',
+        risk: 'low',
+    },
+];
+
+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';
+
+function isMiniProgramBridgeMessage(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const message = value;
+    return (message.namespace === MINI_PROGRAM_MESSAGE_NAMESPACE &&
+        (message.version === 1 || message.version === 2) &&
+        typeof message.nonce === 'string' &&
+        typeof message.type === 'string');
+}
+
+/** 当前用户信息与登录能力支持的完整 scope 目录。 */
+const USER_INFO_AUTHORIZATION_SCOPES = ['identity', 'profile'];
+
+const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(['network.request']);
+function isManagedMiniProgramRuntimePermissionKey(key) {
+    return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
+}
+function parseMiniProgramRuntimePermissions(snapshot) {
+    if (!isRecord(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
+        return { valid: false, permissions: {} };
+    }
+    if (snapshot.revision !== undefined && (typeof snapshot.revision !== 'number' || !Number.isInteger(snapshot.revision) || snapshot.revision < 0)) {
+        return { valid: false, permissions: {} };
+    }
+    const seenKeys = new Set();
+    const permissions = {};
+    for (const rawEntry of snapshot.entries) {
+        if (!isRecord(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
+            return { valid: false, permissions: {} };
+        }
+        const key = rawEntry.key.trim();
+        if (seenKeys.has(key) || (rawEntry.status !== 'enabled' && rawEntry.status !== 'disabled') || !isRecord(rawEntry.config)) {
+            return { valid: false, permissions: {} };
+        }
+        seenKeys.add(key);
+        if (!isManagedMiniProgramRuntimePermissionKey(key))
+            continue;
+        if (key === 'network.request' && typeof rawEntry.config.useOfficialDomain !== 'boolean') {
+            return { valid: false, permissions: {} };
+        }
+        permissions[key] = {
+            key,
+            status: rawEntry.status,
+            config: { useOfficialDomain: rawEntry.config.useOfficialDomain },
+        };
+    }
+    return { valid: true, permissions };
+}
+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, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_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, parseMiniProgramRuntimePermissions };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@heybox/hb-sdk-protocol",
+  "version": "0.7.4-alpha.1",
+  "description": "Heybox mini-program iframe bridge wire contracts.",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "heybox": "./src/index.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs.js",
+      "default": "./dist/index.esm.js"
+    }
+  },
+  "files": [
+    "dist",
+    "types",
+    "src",
+    "README.md"
+  ],
+  "license": "ISC",
+  "dependencies": {},
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@types/node": "24.10.1",
+    "rimraf": "^5.0.5",
+    "rollup": "^4.52.4",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@heybox/hb-types": "~1.0.2"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "build:package": "pnpm run clean && pnpm run build:lib && pnpm run build:types",
+    "build:lib": "rollup -c rollup.config.ts --configPlugin 'typescript={\"tsconfig\":\"tsconfig.build.json\"}'",
+    "build:types": "tsc -p tsconfig.dts.json",
+    "test:types": "tsc -p tsconfig.dts.json --noEmit --pretty false",
+    "clean": "rimraf ./dist && rimraf ./types",
+    "check:boundary": "node scripts/check-boundary.cjs",
+    "test:unit": "NODE_OPTIONS='--conditions=heybox' vitest run",
+    "test:watch": "NODE_OPTIONS='--conditions=heybox' vitest"
+  }
+}

package/src/bridge.ts

@@ -0,0 +1,68 @@
+import { MINI_PROGRAM_MESSAGE_NAMESPACE } from './constants';
+import type { UserInfoAuthorization } from './payloads';
+
+export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event';
+export type MiniProgramEventName =
+  | 'launch'
+  | 'ready'
+  | 'show'
+  | 'hide'
+  | 'unload'
+  | 'error'
+  | 'heybox_app_login_change'
+  | 'user_info_authorization_change';
+
+export interface MiniProgramBridgeError {
+  code: string;
+  message: string;
+  data?: unknown;
+}
+export interface SDKHandshakePayload {
+  href: string;
+  userAgent: string;
+  sdkVersion: string;
+}
+export interface RuntimeLocationProbePayload {
+  probeId: string;
+  timestamp: number;
+}
+export type SDKLocationReportTrigger = 'probe' | 'history' | 'popstate' | 'hashchange' | 'pageshow' | 'resume';
+export interface SDKLocationReportPayload {
+  probeId?: string;
+  href: string;
+  sdkVersion: string;
+  trigger: SDKLocationReportTrigger;
+  timestamp: number;
+}
+export type SDKCSPBlockedResourceType = 'url' | 'inline' | 'eval' | 'unknown';
+export interface SDKCSPViolationPayload {
+  effectiveDirective: string;
+  violatedDirective: string;
+  disposition: string;
+  blockedResourceType: SDKCSPBlockedResourceType;
+  blockedOrigin?: string;
+  redactedPathname?: string;
+  sanitizedPathnameHash?: string;
+  sdkVersion: string;
+  timestamp: number;
+}
+export interface MiniProgramBridgeMessage<TPayload = unknown> {
+  namespace: typeof MINI_PROGRAM_MESSAGE_NAMESPACE;
+  version: 1 | 2;
+  nonce: string;
+  type: MiniProgramBridgeMessageType;
+  id?: string;
+  method?: string;
+  payload?: TPayload;
+  error?: MiniProgramBridgeError;
+}
+export interface MiniProgramEventPayloadMap {
+  launch: { timestamp: number; url?: string };
+  ready: { timestamp: number };
+  show: { timestamp: number; source?: string };
+  hide: { timestamp: number; source?: string };
+  unload: { timestamp: number };
+  error: MiniProgramBridgeError;
+  heybox_app_login_change: { isHeyboxAppLoggedIn: boolean };
+  user_info_authorization_change: UserInfoAuthorization;
+}