@heybox/hb-sdk 0.8.0-alpha.9 → 0.8.0

package/dist/vite.cjs.js

@@ -8,7 +8,30 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.0-alpha.9';
+    : '0.8.0';
+
+/**
+ * iframe 与调试台页面的开发期 console 捕获转发。
+ *
+ * 双条件门控（iframe 转发）：
+ * 1. 构建期：`hb-sdk dev`（vite serve）注入 `false`；`hb-sdk build` /
+ *    `vite build`（生产）永不注入或替换为 `false`，本模块被死代码消除。
+ * 2. 运行期：仅在 `window.name` 为 `__hb_sdk_mini_dev__` 的调试 iframe 中激活，
+ *    用户设备上的正式运行环境没有该标记。
+ *
+ * 无侵入 patch `console.log/debug/info/warn/error`：原样放行（DevTools 不受影响）+
+ * 通过 `window.parent.postMessage` 转发给调试台（CSP 的 connect-src 不约束 postMessage，
+ * 网络上报由调试台页面代理）。发送全程静默：失败不得回打 console，避免自触发死循环。
+ *
+ * 激活时机：由 SDK 默认单例初始化时调用（业务 `import '@heybox/hb-sdk'` 即生效）；
+ * iframe 标记由调试台 `iframe.name` 与 vite dev 注入的无依赖 bootstrap 共同设置。
+ * 调试台页面自身（runtime 跑在这里，`[hb-sdk-runtime]` 日志不经过 iframe）另用
+ * `installMiniDevConsoleSelfCapture` 接入「日志」页签（source: 'host'）。
+ */
+const MINI_DEV_IFRAME_WINDOW_NAME = '__hb_sdk_mini_dev__';
+const MINI_DEV_CONSOLE_EVENT_TYPE = 'hb-sdk:mini-dev-console';
+/** 调试台页面与 iframe bootstrap 共用的已安装标记（window/console 上的属性名）。 */
+const MINI_DEV_CONSOLE_INSTALL_FLAG = '__hb_sdk_mini_dev_console_installed__';
 
 var re = {exports: {}};
 
@@ -2795,6 +2818,197 @@ function requireSemver () {
 
 var semverExports = requireSemver();
 
+const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+const MINI_PROGRAM_MESSAGE_VERSION = 2;
+const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
+
+const MINI_PROGRAM_PERMISSION_KEYS = [
+    'userInfo',
+    'steamLibrary',
+    'share',
+    'storage',
+    'filesystem',
+    'clipboard',
+    'leaderboard',
+    'network',
+];
+const MINI_PROGRAM_PERMISSION_CATALOG = [
+    {
+        key: 'userInfo',
+        name: '用户信息',
+        description: '登录小程序并读取当前用户的授权信息。',
+        access: 'declaration',
+        risk: 'medium',
+        config: {},
+        methods: ['auth.login', 'user.getInfo'],
+        conditions: ['继续执行黑盒登录、用户授权和可信手势规则。'],
+    },
+    {
+        key: 'steamLibrary',
+        name: 'Steam 游戏库',
+        description: '读取当前用户授权的 Steam 游戏库。',
+        access: 'declaration',
+        risk: 'high',
+        config: {},
+        methods: ['user.getSteamGameList'],
+        conditions: ['继续执行账号绑定和数据可用性规则。'],
+    },
+    {
+        key: 'share',
+        name: '分享',
+        description: '使用小程序分享、分享菜单和截图能力。',
+        access: 'declaration',
+        risk: 'medium',
+        config: {},
+        methods: ['share.copyLink', 'share.showShareMenu', 'share.screenshot'],
+        conditions: ['继续执行分享参数校验和 Host 支持检查。'],
+    },
+    {
+        key: 'storage',
+        name: '键值存储',
+        description: '读写按小程序隔离的简单键值数据。',
+        access: 'declaration',
+        risk: 'medium',
+        config: {},
+        methods: ['storage.getStorage', 'storage.setStorage'],
+        conditions: ['仅用于简单键值存储，不包含文件系统。'],
+    },
+    {
+        key: 'filesystem',
+        name: '文件系统',
+        description: '访问小程序沙盒文件和用户选择的外部文件。',
+        access: 'declaration',
+        risk: 'high',
+        config: {},
+        methods: [
+            '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',
+        ],
+        conditions: ['外部文件继续要求有效的用户选择、会话句柄和匹配的读写模式。'],
+    },
+    {
+        key: 'clipboard',
+        name: '剪贴板',
+        description: '向系统剪贴板写入文本。',
+        access: 'declaration',
+        risk: 'medium',
+        config: {},
+        methods: ['device.setClipboard'],
+        conditions: ['继续执行文本长度和 Host 支持限制。'],
+    },
+    {
+        key: 'leaderboard',
+        name: '排行榜',
+        description: '读写小程序云排行榜。',
+        access: 'declaration',
+        risk: 'medium',
+        config: {},
+        methods: [
+            'cloud.leaderboard.submit',
+            'cloud.leaderboard.getList',
+            'cloud.leaderboard.getCurrentUserEntry',
+            'cloud.leaderboard.deleteCurrentUserEntry',
+            'cloud.leaderboard.getInfo',
+        ],
+        conditions: ['排行榜必须已创建，用户和资源规则保持不变。'],
+    },
+    {
+        key: 'network',
+        name: '网络',
+        description: '通过 network 模块请求或下载外部资源。',
+        access: 'platform-approval',
+        risk: 'high',
+        config: {
+            useOfficialDomain: {
+                type: 'boolean',
+                required: false,
+                default: false,
+                description: '是否申请访问小黑盒官方域名。',
+            },
+        },
+        methods: ['network.request', 'network.download'],
+        conditions: ['声明后仍需平台批准，并继续执行网络安全策略。'],
+    },
+];
+new Set(MINI_PROGRAM_PERMISSION_KEYS);
+
+new Set(MINI_PROGRAM_PERMISSION_KEYS);
+
+const MINIAPP_PERMISSION_KEYS = MINI_PROGRAM_PERMISSION_KEYS;
+function parseMiniappPermissions(value, options) {
+    const sourceLabel = options.sourceLabel ?? 'package.json#heybox.permissions';
+    if (!options.present) {
+        if (requiresExplicitPermissions(options.sdkVersion)) {
+            throw new Error(`${sourceLabel} 在 @heybox/hb-sdk ${options.sdkVersion} 中必须声明；无权限需求时请配置空对象 {}`);
+        }
+        return { declared: false };
+    }
+    if (!isRecord$1(value)) {
+        throw new Error(`${sourceLabel} 必须是 JSON 对象`);
+    }
+    const knownKeys = new Set(MINIAPP_PERMISSION_KEYS);
+    for (const key of Object.keys(value)) {
+        if (!knownKeys.has(key))
+            throw new Error(`${sourceLabel} 包含未知权限：${key}`);
+    }
+    const permissions = {};
+    for (const key of MINIAPP_PERMISSION_KEYS) {
+        if (!Object.prototype.hasOwnProperty.call(value, key))
+            continue;
+        const declaration = value[key];
+        const itemLabel = `${sourceLabel}.${key}`;
+        if (!isRecord$1(declaration))
+            throw new Error(`${itemLabel} 必须是 JSON 对象`);
+        const definition = MINI_PROGRAM_PERMISSION_CATALOG.find((item) => item.key === key);
+        if (!definition)
+            throw new Error(`权限目录缺少定义：${key}`);
+        const allowedFields = new Set(['enabled', ...Object.keys(definition.config)]);
+        for (const field of Object.keys(declaration)) {
+            if (!allowedFields.has(field))
+                throw new Error(`${itemLabel} 包含未知字段：${field}`);
+        }
+        if (typeof declaration.enabled !== 'boolean')
+            throw new Error(`${itemLabel}.enabled 必须是 boolean`);
+        let useOfficialDomain = false;
+        if (key === 'network') {
+            if (declaration.useOfficialDomain !== undefined && typeof declaration.useOfficialDomain !== 'boolean') {
+                throw new Error(`${itemLabel}.useOfficialDomain 必须是 boolean`);
+            }
+            useOfficialDomain = declaration.useOfficialDomain === true;
+        }
+        if (!declaration.enabled)
+            continue;
+        permissions[key] = key === 'network' ? { enabled: true, useOfficialDomain } : { enabled: true };
+    }
+    return { declared: true, permissions: permissions };
+}
+function requiresExplicitPermissions(sdkVersion) {
+    const parsed = semverExports.parse(sdkVersion);
+    if (!parsed)
+        throw new Error(`sdkVersion 必须是合法 SemVer：${sdkVersion}`);
+    return parsed.major > 0 || parsed.minor >= 9;
+}
+function getMissingPermissionsWarning(sourceLabel = 'package.json#heybox.permissions') {
+    return `${sourceLabel} 尚未声明。当前按 0.8 兼容行为构建；0.9.0 起将拒绝构建，请尽快补充权限声明（无权限需求时配置 {}）。`;
+}
+function isRecord$1(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', 'linux'];
 function validateMiniappPackageVersionForBuild(version) {
     return validateMiniappManifestVersion(version, 'package.json.version');
@@ -2808,7 +3022,13 @@ function validateMiniappManifestVersion(version, sourceLabel = 'manifest.version
 }
 function renderMiniappManifest(manifest) {
     const platforms = validateMiniappPlatforms(manifest.platforms, 'manifest.platforms');
-    return `${JSON.stringify({ version: manifest.version, sdkVersion: manifest.sdkVersion, platforms }, null, 2)}\n`;
+    const output = {
+        version: manifest.version,
+        sdkVersion: manifest.sdkVersion,
+        platforms,
+        ...(manifest.permissions === undefined ? {} : { permissions: manifest.permissions }),
+    };
+    return `${JSON.stringify(output, null, 2)}\n`;
 }
 function validateMiniappPlatforms(platforms, sourceLabel = 'platforms') {
     if (!Array.isArray(platforms) || platforms.length === 0) {
@@ -2863,6 +3083,21 @@ function findNearestPackageJsonPath(startDir) {
     }
 }
 function readMiniappVersionFromPackageJson(root) {
+    return readMiniappPackageJson(root, true).version;
+}
+function readMiniappPermissionsFromPackageJson(root, sdkVersion) {
+    const { packageJson } = readMiniappPackageJson(root, false);
+    const heybox = packageJson.heybox;
+    if (heybox !== undefined && !isRecord(heybox)) {
+        throw new Error('@heybox/hb-sdk 提示：package.json#heybox 必须是 JSON 对象');
+    }
+    const present = isRecord(heybox) && Object.prototype.hasOwnProperty.call(heybox, 'permissions');
+    return parseMiniappPermissions(isRecord(heybox) ? heybox.permissions : undefined, {
+        present,
+        sdkVersion,
+    });
+}
+function readMiniappPackageJson(root, requireVersion) {
     const packageJsonPath = findNearestPackageJsonPath(root);
     let content;
     try {
@@ -2878,10 +3113,13 @@ function readMiniappVersionFromPackageJson(root) {
     catch (error) {
         throw new Error(`@heybox/hb-sdk 解析 package.json 失败：${formatReason(error)}`);
     }
-    if (typeof packageJson.version !== 'string' || packageJson.version.trim() === '') {
+    if (requireVersion && (typeof packageJson.version !== 'string' || packageJson.version.trim() === '')) {
         throw new Error('@heybox/hb-sdk 提示：package.json.version 必须是非空字符串');
     }
-    return packageJson.version.trim();
+    return { packageJson, version: typeof packageJson.version === 'string' ? packageJson.version.trim() : '' };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function formatReason(error) {
     if (error instanceof Error && error.message) {
@@ -11320,10 +11558,6 @@ function parse(html, options) {
     return Parser.parse(html, options);
 }
 
-const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
-const MINI_PROGRAM_MESSAGE_VERSION = 2;
-const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
-
 const HTML_NAMESPACE = 'http://www.w3.org/1999/xhtml';
 const RUNTIME_GATE_MARKER = 'data-heybox-runtime-gate';
 const RUNTIME_GATE_STYLE_MARKER = 'data-heybox-runtime-gate-style';
@@ -11646,8 +11880,29 @@ function shouldSkipMiniappPlatformCspFromEnv(env = process.env) {
     return env[HB_SDK_RUNTIME_PERMISSION_CONTEXT_ENV] === VERIFIED_RUNTIME_PERMISSION_CONTEXT && env[HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN_ENV] === '1';
 }
 
+/**
+ * dev serve 时在入口 HTML 最早位置注入无依赖 console 捕获 bootstrap。
+ *
+ * 必须内联完整 patch 逻辑而非等 SDK 模块加载：vite client、业务代码的 console 调用
+ * 都可能早于 SDK 单例初始化（如 [vite] connecting）。捕获条件：
+ * 1. 构建期只有 vite serve 走到本分支（生产构建无此代码，双保险之 define 常量仍注入给 SDK 侧）；
+ * 2. 运行期仅调试 iframe（window.name 标记由调试台 iframe.name 与本 bootstrap 设置）激活。
+ * 转发经 window.parent.postMessage（CSP connect-src 不约束 postMessage），失败静默，
+ * 严禁回打 console 造成自触发循环。SDK 侧 installMiniDevConsoleForwarding 安装时
+ * 检测同款 INSTALL_FLAG，不会重复 patch。
+ */
+function injectMiniDevConsoleBootstrap(html) {
+    const bootstrap = `<script>(function(){var LEVELS=['log','debug','info','warn','error'];var FLAG='${MINI_DEV_CONSOLE_INSTALL_FLAG}';var TYPE='${MINI_DEV_CONSOLE_EVENT_TYPE}';if(window.name!=='${MINI_DEV_IFRAME_WINDOW_NAME}')window.name='${MINI_DEV_IFRAME_WINDOW_NAME}';if(window[FLAG])return;var patched=false;for(var i=0;i<LEVELS.length;i++)(function(level){var original=console[level];if(typeof original!=='function')return;console[level]=function(){try{parent.postMessage({type:TYPE,detail:{level:level,args:Array.prototype.slice.call(arguments),timestamp:Date.now()}},'*')}catch(e){}return original.apply(this,arguments)};patched=true})(LEVELS[i]);if(patched)window[FLAG]=true})();</script>`;
+    const headIndex = html.indexOf('<head>');
+    if (headIndex < 0) {
+        return html;
+    }
+    const insertAt = headIndex + '<head>'.length;
+    return `${html.slice(0, insertAt)}${bootstrap}${html.slice(insertAt)}`;
+}
 const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
 const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
+const miniDevLoggingConstant = ['__HB_SDK_DEV', 'LOGGING__'].join('_');
 function miniappManifest(options) {
     const platforms = validateMiniappPlatforms(options?.platforms, 'miniappManifest().platforms');
     const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
@@ -11659,12 +11914,17 @@ function miniappManifest(options) {
     let priorBuildError;
     return {
         name: 'heybox-miniapp-manifest',
-        config(config) {
+        config(config, env) {
             assertMiniappViteBase(config.base);
+            // command 在本钩子时序早于 configResolved，必须取自 env 命令而非闭包；
+            // 旧调用方（测试等）未传 env 时按 build 处理。
+            const isServe = env?.command === 'serve';
             return {
                 ...(config.base === undefined ? { base: './' } : {}),
                 define: {
                     [sdkVersionBuildConstant]: JSON.stringify(resolveSdkVersion()),
+                    // 仅 vite serve（hb-sdk dev）注入；vite build / hb-sdk build 永不注入，捕获模块被死代码消除。
+                    ...(isServe ? { [miniDevLoggingConstant]: 'true' } : {}),
                 },
             };
         },
@@ -11686,12 +11946,12 @@ function miniappManifest(options) {
             }
         },
         transformIndexHtml(html) {
-            return enforceMiniappHtmlPolicy(html, {
+            const enforced = enforceMiniappHtmlPolicy(html, {
                 ...(command === 'serve' ? { hmrWebSocketUrl } : {}),
                 skipPlatformCsp,
             });
-        },
-        async closeBundle() {
+            return command === 'serve' ? injectMiniDevConsoleBootstrap(enforced) : enforced;
+        }, async closeBundle() {
             // Rollup 在 buildStart/transform 失败后仍会调用 closeBundle。
             // 若此时再抛「缺 index.html」等二次错误，会掩盖真实失败原因。
             if (priorBuildError) {
@@ -11699,6 +11959,9 @@ function miniappManifest(options) {
             }
             const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
             const sdkVersion = resolveSdkVersion();
+            const parsedPermissions = readMiniappPermissionsFromPackageJson(root, sdkVersion);
+            if (!parsedPermissions.declared)
+                this.warn(getMissingPermissionsWarning());
             const outputRoot = path.resolve(root, outDir);
             const htmlFiles = collectHtmlFiles(outputRoot);
             const unexpectedHtmlFiles = htmlFiles.filter((file) => path.relative(outputRoot, file) !== 'index.html');
@@ -11714,7 +11977,12 @@ function miniappManifest(options) {
             node_fs.writeFileSync(indexHtmlPath, enforceMiniappHtmlPolicy(node_fs.readFileSync(indexHtmlPath, 'utf8'), { skipPlatformCsp }));
             const manifestPath = path.join(outputRoot, 'manifest.json');
             node_fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
-            node_fs.writeFileSync(manifestPath, renderMiniappManifest({ version, sdkVersion, platforms }));
+            node_fs.writeFileSync(manifestPath, renderMiniappManifest({
+                version,
+                sdkVersion,
+                platforms,
+                ...(parsedPermissions.permissions === undefined ? {} : { permissions: parsedPermissions.permissions }),
+            }));
         },
     };
 }