From 98f62474b6ef0474d1176ed390a401738f361679 Mon Sep 17 00:00:00 2001 From: kdletters Date: Fri, 19 Jun 2026 15:48:48 +0800 Subject: [PATCH] =?UTF-8?q?=E6=94=B6=E7=B4=A7=E5=A4=96=E9=93=BE=E8=BD=BD?= =?UTF-8?q?=E8=8D=B7=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 将 app.openExternalUrl 外链载荷归一化提升到共享 HostBridge 契约 让 H5 facade 和 Expo 移动壳按共享外链 payload 边界发起与消费请求 增加外链载荷测试和三端壳总门禁反查 同步宿主壳协议文档和共享决策记录 --- apps/mobile-shell/scripts/check-config.mjs | 13 +++++++++++++ .../src/host-bridge/bridge.test.ts | 14 ++++++++++++++ apps/mobile-shell/src/host-bridge/dispatch.ts | 7 ++++--- .../shared-memory/decision-log.md | 2 +- ...前端架构】宿主壳能力统一协议-2026-06-17.md | 2 +- .../shared/src/contracts/hostBridge.test.ts | 18 ++++++++++++++++++ packages/shared/src/contracts/hostBridge.ts | 7 +++++++ scripts/check-native-shells.mjs | 18 ++++++++++++++++++ src/services/host-bridge/hostBridge.ts | 19 ++++++++++--------- 9 files changed, 86 insertions(+), 14 deletions(-) diff --git a/apps/mobile-shell/scripts/check-config.mjs b/apps/mobile-shell/scripts/check-config.mjs index 3b11d5a13..9cabc682a 100644 --- a/apps/mobile-shell/scripts/check-config.mjs +++ b/apps/mobile-shell/scripts/check-config.mjs @@ -1479,6 +1479,7 @@ for (const snippet of [ 'normalizeExportedImageFileName', 'normalizeHostBridgeExportFileName', 'normalizeHostBridgeClipboardText', + 'normalizeHostBridgeExternalUrlPayload', 'normalizeHostBridgeHapticsImpactStyle', 'base64Data', 'isHostBridgeMethod', @@ -1494,6 +1495,18 @@ for (const snippet of [ throw new Error(`mobile shell HostBridge missing ${snippet}`); } } +if ( + !hostBridgeSource.includes( + 'const externalUrlPayload = normalizeHostBridgeExternalUrlPayload(', + ) || + !hostBridgeSource.includes('const { url } = externalUrlPayload;') || + !hostBridgeSource.includes('Linking.canOpenURL(url)') || + !hostBridgeSource.includes('Linking.openURL(url)') +) { + throw new Error( + 'mobile shell app.openExternalUrl must normalize payloads with the shared HostBridge external URL boundary', + ); +} if ( !hostBridgeSource.includes( 'const clipboardText = normalizeHostBridgeClipboardText(', diff --git a/apps/mobile-shell/src/host-bridge/bridge.test.ts b/apps/mobile-shell/src/host-bridge/bridge.test.ts index 8f7eeaf19..e92ba4e3a 100644 --- a/apps/mobile-shell/src/host-bridge/bridge.test.ts +++ b/apps/mobile-shell/src/host-bridge/bridge.test.ts @@ -595,6 +595,20 @@ describe('handleMobileHostBridgeMessage', () => { expect(Linking.openURL).not.toHaveBeenCalled(); }); + test('app.openExternalUrl 拒绝控制字符', async () => { + const response = await send( + request('app.openExternalUrl', { + url: 'https://example.com/\nnext', + }), + ); + + const failedResponse = expectFailed(response); + + expect(failedResponse.error.code).toBe('invalid_request'); + expect(Linking.canOpenURL).not.toHaveBeenCalled(); + expect(Linking.openURL).not.toHaveBeenCalled(); + }); + test('重复 HostBridge request id 回放首次结果且不重复触发系统动作', async () => { const duplicateRequest = request('share.open', { title: '测试作品', diff --git a/apps/mobile-shell/src/host-bridge/dispatch.ts b/apps/mobile-shell/src/host-bridge/dispatch.ts index 1d2211b43..492ea94b5 100644 --- a/apps/mobile-shell/src/host-bridge/dispatch.ts +++ b/apps/mobile-shell/src/host-bridge/dispatch.ts @@ -21,7 +21,7 @@ import { normalizeHostBridgeBadgeCount, normalizeHostBridgeClipboardText, normalizeHostBridgeColorScheme, - normalizeHostBridgeExternalUrl, + normalizeHostBridgeExternalUrlPayload, normalizeHostBridgeHapticsImpactStyle, normalizeHostBridgeLocalNotification, type OpenExternalUrlPayload, @@ -71,13 +71,14 @@ export function configureMobileHostBridgeNavigation( } async function openExternalUrl(payload: unknown) { - const url = normalizeHostBridgeExternalUrl( + const externalUrlPayload = normalizeHostBridgeExternalUrlPayload( (payload as OpenExternalUrlPayload | undefined)?.url, ); - if (!url) { + if (!externalUrlPayload) { throw invalidRequest('url must use an allowed external protocol'); } + const { url } = externalUrlPayload; if (!(await Linking.canOpenURL(url))) { throw { code: 'host_error', diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 90bbca6e5..f556b76b4 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -2571,7 +2571,7 @@ ## 2026-06-19 HostBridge 载荷边界单一来源 - 背景：文件导入导出、剪贴板、角标、本地通知和 request id 都已经在 Expo 与 Tauri 两套壳里有运行时校验；如果 MIME 清单、字节上限或文本长度只靠人工同步，新增文件类型或调整上限时会出现 H5 契约、移动壳和桌面壳互相漂移。 -- 决策：`packages/shared/src/contracts/hostBridge.ts` 是 HostBridge 载荷边界的声明来源，导出文本 / 图片 / 音频 MIME 清单、文档导入 MIME 清单、导入 / 导出字节上限、导出文件名 fallback / 长度上限、request id 长度、角标上限、窗口标题长度、剪贴板文本长度、触觉反馈 style 和本地通知标题 / 正文长度。Expo 移动壳必须直接导入这些共享常量，`apps/mobile-shell/scripts/check-config.mjs` 会拒绝移动壳重新本地声明文件大小或 MIME 清单；移动壳 `file.importText` / `file.importDocument` / `file.importAudio` 必须在读取文本内容或 base64 前，通过 picker `size` 或 Expo `File.size` 拿到可信 byte count 并完成上限校验，无法拿到可信大小时直接拒绝导入。`app.setTitle` 必须拒绝空值和控制字符，并按共享 80 字符上限截断；H5 facade 和 Tauri 壳都执行该边界。`clipboard.writeText` / `clipboard.readText` 两个方向都必须执行同一个 100000 字符上限；H5 facade 发起 `clipboard.writeText` 前先按共享上限归一化 payload，Expo 与 Tauri 壳仍必须再次执行同一边界，不允许只信 H5 facade 的预校验。H5 facade 发起 `haptics.impact` 前也必须按共享 style 清单归一化，未知 style 不发往宿主，Expo 壳仍二次拒绝未知值。`file.exportText` 的可选 `mimeType` 只能来自 `HOST_BRIDGE_TEXT_MIME_TYPES`，缺省为 `text/plain`，Expo 与 Tauri 都必须拒绝图片、音频或二进制 MIME，避免 H5 通过文本导出通道伪装落盘；两端 config check 必须反查该边界。Tauri 桌面壳按 Rust 运行时代码镜像实现，`apps/desktop-shell/scripts/check-config.mjs` 必须反查共享契约并拒绝漂移。 +- 决策：`packages/shared/src/contracts/hostBridge.ts` 是 HostBridge 载荷边界的声明来源，导出文本 / 图片 / 音频 MIME 清单、文档导入 MIME 清单、导入 / 导出字节上限、导出文件名 fallback / 长度上限、request id 长度、角标上限、窗口标题长度、外链 URL payload、剪贴板文本长度、触觉反馈 style 和本地通知标题 / 正文长度。Expo 移动壳必须直接导入这些共享常量，`apps/mobile-shell/scripts/check-config.mjs` 会拒绝移动壳重新本地声明文件大小或 MIME 清单；移动壳 `file.importText` / `file.importDocument` / `file.importAudio` 必须在读取文本内容或 base64 前，通过 picker `size` 或 Expo `File.size` 拿到可信 byte count 并完成上限校验，无法拿到可信大小时直接拒绝导入。`app.openExternalUrl` 必须先通过共享 `normalizeHostBridgeExternalUrlPayload()` 清洗为 `{ url }`，H5 facade 和 Expo 移动壳都执行该边界，Tauri 壳用 Rust URL parser 镜像同一协议清单。`app.setTitle` 必须拒绝空值和控制字符，并按共享 80 字符上限截断；H5 facade 和 Tauri 壳都执行该边界。`clipboard.writeText` / `clipboard.readText` 两个方向都必须执行同一个 100000 字符上限；H5 facade 发起 `clipboard.writeText` 前先按共享上限归一化 payload，Expo 与 Tauri 壳仍必须再次执行同一边界，不允许只信 H5 facade 的预校验。H5 facade 发起 `haptics.impact` 前也必须按共享 style 清单归一化，未知 style 不发往宿主，Expo 壳仍二次拒绝未知值。`file.exportText` 的可选 `mimeType` 只能来自 `HOST_BRIDGE_TEXT_MIME_TYPES`，缺省为 `text/plain`，Expo 与 Tauri 都必须拒绝图片、音频或二进制 MIME，避免 H5 通过文本导出通道伪装落盘；两端 config check 必须反查该边界。Tauri 桌面壳按 Rust 运行时代码镜像实现，`apps/desktop-shell/scripts/check-config.mjs` 必须反查共享契约并拒绝漂移。 - 影响范围：`packages/shared/src/contracts/hostBridge.ts`、`apps/mobile-shell/src/host-bridge/files.ts`、`apps/mobile-shell/scripts/check-config.mjs`、`apps/desktop-shell/src-tauri/src/host_bridge/`、`apps/desktop-shell/scripts/check-config.mjs`、Expo / Tauri HostBridge 方案文档。 - 验证方式：`npm run mobile-shell:typecheck`、`npm run desktop-shell:typecheck`、`npm run test -- packages/shared/src/contracts/hostBridge.test.ts`、`npm run check:native-shells`、`npm run check:encoding`、`git diff --check`。 diff --git a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md index 595b54596..8debabd11 100644 --- a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md +++ b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md @@ -68,7 +68,7 @@ Tauri 桌面壳启动时必须按 `label="main"` 解析 `tauri.conf.json` 主窗 - `setHostAppTitle()`：原生 App 宿主的受控窗口标题入口。H5 主站会按当前平台阶段先同步 `document.title`，再通过 `app.setTitle` 请求宿主窗口标题同步；H5 facade 和 Tauri 桌面壳都必须按共享契约 `HOST_BRIDGE_APP_TITLE_MAX_LENGTH` 清洗标题，拒绝空值和控制字符，最多保留 80 个字符。Tauri 桌面壳支持该能力，Expo 移动壳不声明时静默忽略。 - `setHostAppBadgeCount()`：原生 App 宿主的受控应用角标入口。H5 只传 `0` 到共享契约 `HOST_BRIDGE_BADGE_COUNT_MAX` 之间的整数，`0` 表示清除角标；Expo 移动壳只在 iOS 声明 `app.setBadgeCount` 并通过 React Native `PushNotificationIOS` 设置应用图标角标，Android 不声明该能力；Tauri 桌面壳通过主窗口 `set_badge_count` 设置任务栏角标，底层平台不支持时返回明确错误，由 H5 视作失败并继续主流程。当前 H5 只把“可见作品架里未读的草稿生成完成更新”同步为角标数，同一个草稿有多个恢复 ID 时只计 1，已读、失败、生成中和不可见草稿不计入；宿主不支持或设置失败不改变 H5 红点、作品架或后端状态。平台壳同步层必须通过真实 `host_bridge_request` transport 测到 `app.setBadgeCount` 请求，保证未读计数模型和原生壳消费链路同时被门禁覆盖。 - `reloadHostWebView()`：原生 App 宿主的受控 WebView 刷新入口。H5 只能请求刷新当前承载主站的宿主 WebView；Expo 移动壳调用当前 `react-native-webview` 的 `reload()`，Tauri 桌面壳调用主 `WebviewWindow.reload()`。该能力不接受 payload，不开放任意 URL 导航、脚本执行、Tauri guest API 或 RN WebView ref；成功只表示宿主已发起刷新，刷新后当前 H5 上下文会卸载。`AuthGate` 在登录态从未登录变为已登录、或从已登录变为未登录时优先调用该能力刷新当前容器；宿主未声明、返回失败或不可用时再回退浏览器 `window.location.reload()`。 -- `openHostExternalUrl()`：原生 App 宿主的受控外链入口。H5 中需要离开主站的外链在 `native_app` 下先通过 `app.openExternalUrl` 请求宿主系统浏览器打开；只允许 `http:`、`https:`、`mailto:`、`tel:`，相对路径会先归一化到当前站点绝对 URL。宿主不可用或拒绝时回退浏览器外链行为，普通浏览器和小程序保持原有 `` 语义。H5 支付链接和微信 OAuth 登录授权 URL 也走该入口：原生壳未声明真实 `payment.request` / `auth.requestLogin` 前，微信 H5 支付 URL 和后端返回的微信登录授权 URL 优先交给宿主系统浏览器，宿主未处理时才回退当前 WebView 跳转；不得把 H5 支付或网页登录伪装成已完成的原生支付 / 原生登录。 +- `openHostExternalUrl()`：原生 App 宿主的受控外链入口。H5 中需要离开主站的外链在 `native_app` 下先通过 `app.openExternalUrl` 请求宿主系统浏览器打开；只允许 `http:`、`https:`、`mailto:`、`tel:`，相对路径会先归一化到当前站点绝对 URL，再通过共享契约 `normalizeHostBridgeExternalUrlPayload()` 清洗为 `{ url }` 载荷。Expo 移动壳消费该共享 payload normalizer，Tauri 桌面壳在 Rust 侧用 URL parser 镜像同一协议清单。宿主不可用或拒绝时回退浏览器外链行为，普通浏览器和小程序保持原有 `` 语义。H5 支付链接和微信 OAuth 登录授权 URL 也走该入口：原生壳未声明真实 `payment.request` / `auth.requestLogin` 前，微信 H5 支付 URL 和后端返回的微信登录授权 URL 优先交给宿主系统浏览器，宿主未处理时才回退当前 WebView 跳转；不得把 H5 支付或网页登录伪装成已完成的原生支付 / 原生登录。 - `navigateHostNativePage()`：受控跳转宿主页，供订阅授权、支付、登录和内置独立 H5 体验入口等 adapter 复用。Expo 移动壳首版只接受同源 H5 route 并切换 WebView URL；Tauri 桌面壳同样只接受 `https://app.genarrative.world` 同源 H5 route 并在主窗口内跳转。平台首页的儿童动作热身 Demo 入口在 `native_app` 且宿主声明 `navigation.openNativePage` 时必须优先走该 facade 跳转 `/child-motion-demo`，普通浏览器、小程序和未声明能力的裁剪壳才回退浏览器跳转。真正原生页面、登录和支付能力必须等对应 SDK / 页面接入后再声明支持。 - `exportHostTextFile()`：原生 App 宿主的受控文本导出入口。Expo 移动壳通过 `file.exportText` 写入缓存文本文件并交给系统分享 / 保存面板；Tauri 桌面壳通过 `file.exportText` 打开系统保存对话框并写入用户选择的文件。文件名必须清洗，单次文本不超过 5 MiB，可选 MIME 只能来自共享契约 `HOST_BRIDGE_TEXT_MIME_TYPES`，未传时默认为 `text/plain`，非文本 MIME 必须拒绝，不能借文本导出通道伪装成图片、音频或二进制文件；成功只返回文件名和字节数，不把本机绝对路径暴露给 H5；系统分享不可用或用户取消时返回明确错误，由 H5 fallback 承接。创作 Agent 工作台在 `native_app` 且声明该能力时提供会话 Markdown 导出入口，导出内容只来自当前 H5 已持有的会话标题、摘要、进度、锚点、消息、流式回复和输入草稿，并在 H5 侧先按同一 5 MiB 上限做 UTF-8 byte 校验；普通浏览器、小程序和未声明能力的裁剪壳不展示该入口。 - `importHostTextFile()`：原生 App 宿主的受控文本导入入口。Expo 移动壳通过 Expo DocumentPicker 打开系统文档选择器，Tauri 桌面壳通过系统文件选择框读取用户选择的文本文件；两端都只接受 `text/plain`、`text/markdown`、`text/csv`、`application/json` 或对应扩展名，单次不超过 5 MiB，成功只返回清洗后的文件名、MIME、UTF-8 文本内容和字节数，不暴露设备本地 URI 或本机绝对路径，也不开放通用文件系统能力；宿主必须在读取文本内容前拿到可信 byte count 并完成上限校验，移动壳在 picker 缺少 `size` 时改用 Expo `File.size`，仍拿不到可信大小时直接拒绝导入；用户取消时由 H5 facade 归为 `false`。创作 Agent 工作台在 `native_app` 且声明该能力时优先调用宿主文本导入，并把结果转换成现有浏览器 `File` 后继续复用后端 `/api/runtime/creation-agent/document-inputs/parse` 解析链路；普通浏览器、小程序和未声明能力的裁剪壳继续使用原文件输入。 diff --git a/packages/shared/src/contracts/hostBridge.test.ts b/packages/shared/src/contracts/hostBridge.test.ts index 6736fa419..8b9706c46 100644 --- a/packages/shared/src/contracts/hostBridge.test.ts +++ b/packages/shared/src/contracts/hostBridge.test.ts @@ -39,6 +39,7 @@ import { normalizeHostBridgeConnectionType, normalizeHostBridgeExportFileName, normalizeHostBridgeExternalUrl, + normalizeHostBridgeExternalUrlPayload, normalizeHostBridgeHapticsImpactStyle, normalizeHostBridgeLifecycleState, normalizeHostBridgeLocalNotification, @@ -287,6 +288,23 @@ describe('HostBridge shared contract helpers', () => { expect(normalizeHostBridgeRequestId(null)).toBeNull(); }); + test('归一化宿主外链打开载荷', () => { + expect( + normalizeHostBridgeExternalUrlPayload(' https://example.com/path '), + ).toEqual({ + url: 'https://example.com/path', + }); + expect(normalizeHostBridgeExternalUrlPayload('mailto:hi@example.com')).toEqual({ + url: 'mailto:hi@example.com', + }); + expect(normalizeHostBridgeExternalUrlPayload('')).toBeNull(); + expect(normalizeHostBridgeExternalUrlPayload('bad\nurl')).toBeNull(); + expect( + normalizeHostBridgeExternalUrlPayload('javascript:alert(1)'), + ).toBeNull(); + expect(normalizeHostBridgeExternalUrlPayload(null)).toBeNull(); + }); + test('归一化宿主剪贴板读取文本', () => { expect(normalizeHostBridgeClipboardText('作品号 PZ-1')).toEqual({ text: '作品号 PZ-1', diff --git a/packages/shared/src/contracts/hostBridge.ts b/packages/shared/src/contracts/hostBridge.ts index 516aba6b0..a0f8f2f4c 100644 --- a/packages/shared/src/contracts/hostBridge.ts +++ b/packages/shared/src/contracts/hostBridge.ts @@ -471,6 +471,13 @@ export function normalizeHostBridgeExternalUrl(rawUrl: unknown) { } } +export function normalizeHostBridgeExternalUrlPayload( + rawUrl: unknown, +): OpenExternalUrlPayload | null { + const url = normalizeHostBridgeExternalUrl(rawUrl); + return url ? { url } : null; +} + export type ClipboardWriteTextPayload = { text: string; }; diff --git a/scripts/check-native-shells.mjs b/scripts/check-native-shells.mjs index be2fd3969..f74702a91 100644 --- a/scripts/check-native-shells.mjs +++ b/scripts/check-native-shells.mjs @@ -1029,6 +1029,24 @@ function assertH5HostBridgePayloadBoundaries() { 'H5 HostBridge facade must use shared HOST_BRIDGE_SCANNER_TIMEOUT_MS', ); } + if ( + !h5HostBridgeSource.includes( + 'return normalizeHostBridgeExternalUrlPayload(trimmedUrl);', + ) || + !h5HostBridgeSource.includes( + 'return normalizeHostBridgeExternalUrlPayload(\n new URL(trimmedUrl, window.location.origin).toString(),\n );', + ) || + !h5HostBridgeSource.includes( + 'const normalizedPayload = normalizeHostExternalUrlPayload(url);', + ) || + !h5HostBridgeSource.includes( + "return await requestNativeHostBoolean(\n 'app.openExternalUrl',\n normalizedPayload,\n );", + ) + ) { + throw new Error( + 'H5 HostBridge facade must normalize app.openExternalUrl payloads with the shared external URL boundary', + ); + } if ( !h5HostBridgeSource.includes( 'const clipboardText = normalizeHostBridgeClipboardText(text);', diff --git a/src/services/host-bridge/hostBridge.ts b/src/services/host-bridge/hostBridge.ts index 36d8faf5a..e845b9aba 100644 --- a/src/services/host-bridge/hostBridge.ts +++ b/src/services/host-bridge/hostBridge.ts @@ -42,7 +42,7 @@ import { normalizeHostBridgeClipboardText, normalizeHostBridgeColorScheme, normalizeHostBridgeConnectionType, - normalizeHostBridgeExternalUrl, + normalizeHostBridgeExternalUrlPayload, normalizeHostBridgeHapticsImpactStyle, normalizeHostBridgeLifecycleState, normalizeHostBridgeLocalNotification, @@ -566,18 +566,18 @@ function buildAbsoluteUrl(value: string) { return new URL(value, window.location.origin).href; } -function normalizeHostExternalUrl(url: string) { +function normalizeHostExternalUrlPayload(url: string) { const trimmedUrl = url.trim(); if (!trimmedUrl) { return null; } if (typeof window === 'undefined') { - return normalizeHostBridgeExternalUrl(trimmedUrl); + return normalizeHostBridgeExternalUrlPayload(trimmedUrl); } try { - return normalizeHostBridgeExternalUrl( + return normalizeHostBridgeExternalUrlPayload( new URL(trimmedUrl, window.location.origin).toString(), ); } catch { @@ -667,15 +667,16 @@ export async function openHostExternalUrl({ url }: HostExternalUrlRequest) { return false; } - const normalizedUrl = normalizeHostExternalUrl(url); - if (!normalizedUrl) { + const normalizedPayload = normalizeHostExternalUrlPayload(url); + if (!normalizedPayload) { return false; } try { - return await requestNativeHostBoolean('app.openExternalUrl', { - url: normalizedUrl, - }); + return await requestNativeHostBoolean( + 'app.openExternalUrl', + normalizedPayload, + ); } catch { return false; }