GenarrativeAI/Genarrative
11
0
Fork 0
Code Issues 18 Pull Requests 3 Actions Packages Projects 3 Releases Wiki Activity

收口原生壳未声明能力覆盖

Browse Source 
移动壳测试从共享 HostBridge method 和 iOS capability profile 派生未声明 method 覆盖

原生壳门禁反查 H5 native request 能力统一 helper 门控和移动壳派生测试

架构文档补齐移动端和桌面端 file.importText 能力清单与未声明 method 规则
This commit is contained in:
段舒康
2026-06-20 03:43:04 +08:00
parent 74567e8bb3
commit 79708e69b2
6 changed files with 39 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/mobile-shell/scripts/check-config.mjs
+17
View File
@@ -14,6 +14,8 @@ const appearancePath = new URL('../src/host-bridge/appearance.ts', import.meta.u
const appearanceSource = fs.readFileSync(appearancePath, 'utf8');
const bridgePath = new URL('../src/host-bridge/bridge.ts', import.meta.url);
const bridgeSource = fs.readFileSync(bridgePath, 'utf8');
const bridgeTestPath = new URL('../src/host-bridge/bridge.test.ts', import.meta.url);
const bridgeTestSource = fs.readFileSync(bridgeTestPath, 'utf8');
const badgePath = new URL('../src/host-bridge/badge.ts', import.meta.url);
const badgeSource = fs.readFileSync(badgePath, 'utf8');
const clipboardPath = new URL('../src/host-bridge/clipboard.ts', import.meta.url);
@@ -817,6 +819,21 @@ if (
throw new Error('mobile shell must not redeclare HostBridge capability profiles');
}
for (const snippet of [
'HOST_BRIDGE_METHODS',
'HOST_BRIDGE_EXPO_MOBILE_IOS_CAPABILITIES',
'const IOS_UNDECLARED_HOST_BRIDGE_METHODS = HOST_BRIDGE_METHODS.filter(',
'(method) => !HOST_BRIDGE_EXPO_MOBILE_IOS_CAPABILITIES.includes(method)',
'test.each(IOS_UNDECLARED_HOST_BRIDGE_METHODS)',
"expect(failedResponse.error.code).toBe('unsupported_method')",
]) {
if (!bridgeTestSource.includes(snippet)) {
throw new Error(
`mobile shell bridge tests must derive unsupported method coverage from shared profiles: ${snippet}`,
);
}
}
const unknownSharedEvents = sharedEvents.filter(
(eventName) => !sharedCapabilities.includes(eventName),
);
apps/mobile-shell/src/host-bridge/bridge.test.ts
+7 -2
View File
@@ -16,6 +16,8 @@ import { afterEach, describe, expect, test, vi } from 'vitest';
import {
HOST_BRIDGE_BADGE_COUNT_MAX,
HOST_BRIDGE_EXPO_MOBILE_IOS_CAPABILITIES,
HOST_BRIDGE_METHODS,
HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID,
HOST_BRIDGE_PROTOCOL,
HOST_BRIDGE_RESPONSE_CACHE_MAX,
@@ -60,6 +62,9 @@ const TEST_MOBILE_URL_OPTIONS: MobileShellUrlOptions = {
hostVersion: '0.1.0',
capabilities: ['host.getRuntime', 'share.open'],
};
const IOS_UNDECLARED_HOST_BRIDGE_METHODS = HOST_BRIDGE_METHODS.filter(
(method) => !HOST_BRIDGE_EXPO_MOBILE_IOS_CAPABILITIES.includes(method),
);
function encodeBytes(bytes: readonly number[]) {
return Buffer.from(bytes).toString('base64');
@@ -501,8 +506,8 @@ describe('handleMobileHostBridgeMessage', () => {
expect(failedResponse.error.code).toBe('unsupported_method');
});
test.each(['auth.requestLogin', 'payment.request'] as const)(
'%s 未接入真实渠道前明确返回 unsupported',
test.each(IOS_UNDECLARED_HOST_BRIDGE_METHODS)(
'%s 未被移动壳声明时明确返回 unsupported',
async (method) => {
const response = await send(request(method));
docs/project-memory/shared-memory/decision-log.md
+2 -1
View File
@@ -41,7 +41,8 @@
- 2026-06-19 桌面壳文件桥接执行边界：Tauri `file.exportText` / `file.importText` / `file.importDocument` / `file.exportImage` / `file.importImage` / `file.importAudio` / `file.exportAudio` 的系统文件对话框过滤器、用户取消语义、路径转换、异步读写编排和 HostBridge 响应统一收口在 `apps/desktop-shell/src-tauri/src/host_bridge/files.rs`；`dispatch.rs` 只负责按 method 委托 `export_desktop_host_bridge_*_file(...)` / `import_desktop_host_bridge_*_file(...)`。桌面壳配置检查会拒绝分发层直接调用 `.dialog()`、`blocking_save_file` / `blocking_pick_file`、文件 payload helper 或落盘 helper，避免文件访问边界重新散落。
- 2026-06-19 桌面壳外链打开 helper 共用：Tauri WebView 外域拦截和 HostBridge `app.openExternalUrl` 都必须复用 `open_normalized_desktop_external_url` 执行系统外链打开动作；HostBridge 分支仍先用 `normalize_external_url` 保留 payload 错误语义并把 opener 错误回传给 H5，WebView 拦截保持 best-effort 静默处理。桌面壳配置检查会拒绝 `dispatch.rs` 直接调用 `app.opener().open_url` 绕过该 helper，避免两条离壳路径漂移。
- 2026-06-18 能力声明收紧：`packages/shared/src/contracts/hostBridge.ts` 提供 HostBridge method / capability 白名单，H5 的 `getHostRuntime()` 会解析并过滤 `hostCapabilities`；`openHostShare`、`writeHostClipboardText`、`requestHostHapticsImpact`、`setHostAppTitle`、`exportHostTextFile` 等 native 能力只在宿主声明对应 capability 后调用。发布分享弹窗只有声明 `share.open` 时才显示“系统分享”，避免旧壳或裁剪壳露出不可用入口。
- 2026-06-20 H5 原生能力门控收口：除 `host.getRuntime` 为了支持旧入口 URL 缺少 capability 时回读真实 runtime 可保留特殊判断外，H5 facade 中所有 native_app request 能力都必须通过 `canUseNativeHostCapability(...)` 统一门控，不得在业务能力函数内直接读取 `runtime.hostCapabilities.includes(...)`，避免导航、登录、支付和其它能力各自复制门控规则。
- 2026-06-20 H5 原生能力门控收口：除 `host.getRuntime` 为了支持旧入口 URL 缺少 capability 时回读真实 runtime 可保留特殊判断外，H5 facade 中所有 native_app request 能力都必须通过 `canUseNativeHostCapability(...)` 统一门控，不得在业务能力函数内直接读取 `runtime.hostCapabilities.includes(...)`，避免各能力复制门控规则；根级 `npm run check:native-shells` 会从共享 `HOST_BRIDGE_METHODS` 自动派生需门控的 request capability 清单，新增 method 时必须同步补齐 H5 facade 门控。
- 2026-06-20 移动壳未声明 method 覆盖：Expo 移动壳对未进入 `HOST_BRIDGE_EXPO_MOBILE_IOS_CAPABILITIES` 的共享 request method 必须由测试从 `HOST_BRIDGE_METHODS` 自动派生覆盖，并在请求到达时返回明确 `unsupported_method`；平台差异能力如 Android 不声明的 `app.setBadgeCount` 保持独立 `unsupported_capability` 语义，不混入未声明 method 清单。
- 2026-06-18 宿主 runtime 回读：主 App 启动时会通过真实 `host.getRuntime` 回读 Expo / Tauri runtime 并缓存过滤后的能力清单，能力来源为 URL `hostCapabilities` 与宿主真实回包的并集；裁剪壳或旧入口 URL 缺少 `hostCapabilities` 时也能启用真实声明能力，但仍不会仅凭 `native_app` 或 transport 存在推断能力可用。该回读请求的短超时由共享契约 `HOST_BRIDGE_RUNTIME_REFRESH_TIMEOUT_MS` 声明，H5 facade 不得本地重声明。
- 2026-06-18 壳能力防漂移：`npm run mobile-shell:typecheck` 与 `npm run desktop-shell:typecheck` 会校验 Expo / Tauri 壳声明的 capability 均来自共享 HostBridge 白名单，并校验壳 runtime 回包、H5 URL `hostCapabilities` 和实现分支保持一致；微信小程序 `WECHAT_HOST_CAPABILITIES` 由 `miniprogram/host-bridge/protocol.test.js` 和根级 `npm run check:native-shells` 反查共享 `HOST_BRIDGE_WECHAT_MINI_PROGRAM_CAPABILITIES`。新增能力必须先更新契约和真实壳实现，再通过这些检查。
- 2026-06-19 宿主上下文 query 契约收口：`packages/shared/src/contracts/hostBridge.ts` 是宿主上下文 query 字段和值的唯一 TypeScript 来源；`HOST_BRIDGE_RUNTIME_CONTEXT_QUERY_KEY` 覆盖 H5 runtime parser 字段，`HOST_BRIDGE_NATIVE_APP_QUERY_KEY` / `HOST_BRIDGE_NATIVE_APP_QUERY_KEYS` / `HOST_BRIDGE_NATIVE_APP_QUERY` 固定 Expo / Tauri 原生壳入口 query，`HOST_BRIDGE_WECHAT_MINI_PROGRAM_SOURCE_QUERY` 固定微信 WebView 来源标记，`HOST_BRIDGE_PRESERVED_RUNTIME_CONTEXT_QUERY_KEYS` 固定 H5 页面内导航需要保留的宿主字段。Expo 壳直接引用共享常量，Tauri Rust 和微信 CommonJS 镜像由 `npm run check:native-shells` / 单壳配置检查反查；微信请求头必须从 `WEB_VIEW_SOURCE_QUERY` 读取 `clientType` / `clientRuntime`，不得另起常量。
docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md
+3 -3
View File
File diff suppressed because one or more lines are too long
docs/【前端架构】宿主壳能力统一协议-2026-06-17.md
+1 -1
View File
@@ -92,7 +92,7 @@ Tauri 桌面壳的文件能力边界统一在 `apps/desktop-shell/src-tauri/src/
2. `authService` 保留原导出，但内部委托 HostBridge，避免一次性改动 AuthGate。
3. 分享弹窗、分享目标同步、九宫切图、微信小程序支付和订阅授权改用 HostBridge 通用接口；旧微信命名服务只作为兼容导出。
4. 后续新增 `native_app` adapter 时只补桥接实现和测试，业务层不新增平台分叉；主 App 启动会触发一次 `host.getRuntime` 回读并订阅能力变化，避免裁剪壳或旧入口 URL 缺少 `hostCapabilities` 时长期隐藏真实可用能力。
5. 每次新增或调整 native capability、HostBridge event 或宿主上下文 query 后，必须先更新 `packages/shared/src/contracts/hostBridge.ts` 中对应微信 / Expo / Tauri capability profile、事件白名单和 query 契约，再运行 `npm run check:native-shells`，统一覆盖 H5 HostBridge 关键测试、三端桥接层文件结构门禁、微信小程序页面路由与 H5 常量反查、Expo 壳 typecheck / test / config smoke / Metro export smoke、Tauri 壳 typecheck / cargo test、桌面 release `--no-bundle` 构建烟测，以及可分发壳与 H5 HostBridge 真实调用链的临时替身词扫描。桌面壳未声明的共享 request method 必须自动派生为 `unsupported_method` 覆盖清单，当前包括 `auth.requestLogin`、`payment.request`、`file.captureImage`、`scanner.scanQrCode` 和 `haptics.impact`，不得伪造成功；H5 facade 除 `host.getRuntime` 真实回读外，所有 native_app request 能力都必须通过 `canUseNativeHostCapability(...)` 统一门控；排查单端问题时再单独运行 `npm run mobile-shell:typecheck`、`npm run mobile-shell:test`、`npm run mobile-shell:config`、`npm run mobile-shell:export`、`npm run desktop-shell:typecheck`、`npm run desktop-shell:test` 或 `npm run desktop-shell:build -- --no-bundle`。
5. 每次新增或调整 native capability、HostBridge event 或宿主上下文 query 后，必须先更新 `packages/shared/src/contracts/hostBridge.ts` 中对应微信 / Expo / Tauri capability profile、事件白名单和 query 契约，再运行 `npm run check:native-shells`，统一覆盖 H5 HostBridge 关键测试、三端桥接层文件结构门禁、微信小程序页面路由与 H5 常量反查、Expo 壳 typecheck / test / config smoke / Metro export smoke、Tauri 壳 typecheck / cargo test、桌面 release `--no-bundle` 构建烟测，以及可分发壳与 H5 HostBridge 真实调用链的临时替身词扫描。桌面壳未声明的共享 request method 必须自动派生为 `unsupported_method` 覆盖清单，当前包括 `auth.requestLogin`、`payment.request`、`file.captureImage`、`scanner.scanQrCode` 和 `haptics.impact`，不得伪造成功；Expo 移动壳未声明的共享 request method 必须由 `HOST_BRIDGE_METHODS - HOST_BRIDGE_EXPO_MOBILE_IOS_CAPABILITIES` 自动派生测试覆盖，确保未接 SDK / 渠道的 method 返回明确 `unsupported_method`；H5 facade 除 `host.getRuntime` 真实回读外，所有 native_app request 能力都必须通过 `canUseNativeHostCapability(...)` 统一门控，根级门禁会从共享 `HOST_BRIDGE_METHODS` 自动派生需检查清单；排查单端问题时再单独运行 `npm run mobile-shell:typecheck`、`npm run mobile-shell:test`、`npm run mobile-shell:config`、`npm run mobile-shell:export`、`npm run desktop-shell:typecheck`、`npm run desktop-shell:test` 或 `npm run desktop-shell:build -- --no-bundle`。
## 验收
scripts/check-native-shells.mjs
+9 -5
View File
@@ -987,10 +987,18 @@ function assertH5HostBridgeEventSubscriptionGates() {
}
function assertH5HostBridgePayloadBoundaries() {
const sharedContractSource = fs.readFileSync(
'packages/shared/src/contracts/hostBridge.ts',
'utf8',
);
const h5HostBridgeSource = fs.readFileSync(
'src/services/host-bridge/hostBridge.ts',
'utf8',
);
const nativeRequestCapabilities = extractTsStringArray(
sharedContractSource,
'HOST_BRIDGE_METHODS',
).filter((method) => method !== 'host.getRuntime');
for (const sharedBoundary of [
'HOST_BRIDGE_RUNTIME_REFRESH_TIMEOUT_MS',
@@ -1149,11 +1157,7 @@ function assertH5HostBridgePayloadBoundaries() {
'H5 HostBridge facade must normalize app.setTitle payloads with the shared title boundary',
);
}
for (const nativeCapability of [
'navigation.openNativePage',
'auth.requestLogin',
'payment.request',
]) {
for (const nativeCapability of nativeRequestCapabilities) {
if (
h5HostBridgeSource.includes(
`runtime.hostCapabilities.includes('${nativeCapability}')`,