From ee49c26868cbed2846320666cc8f21d3bf96022b Mon Sep 17 00:00:00 2001 From: kdletters Date: Thu, 18 Jun 2026 00:35:14 +0800 Subject: [PATCH] =?UTF-8?q?=E6=94=B6=E7=B4=A7=E7=A7=BB=E5=8A=A8=E5=A3=B3?= =?UTF-8?q?=E5=A4=96=E9=93=BE=E5=8D=8F=E8=AE=AE=E7=99=BD=E5=90=8D=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Expo WebView 外域导航只允许安全外链协议交给系统 阻断危险协议避免外链页面保留宿主桥能力 补充移动壳导航测试和宿主壳文档 --- apps/mobile-shell/App.tsx | 10 ++++++++-- .../src/mobileShellNavigation.test.ts | 16 ++++++++++++++++ apps/mobile-shell/src/mobileShellNavigation.ts | 6 ++++++ .../project-memory/shared-memory/decision-log.md | 1 + ...】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md | 4 ++-- 5 files changed, 33 insertions(+), 4 deletions(-) diff --git a/apps/mobile-shell/App.tsx b/apps/mobile-shell/App.tsx index 74ba95bc..49a4a7f5 100644 --- a/apps/mobile-shell/App.tsx +++ b/apps/mobile-shell/App.tsx @@ -10,7 +10,10 @@ import { MOBILE_HOST_CAPABILITIES, } from './src/mobileHostBridge'; import { buildMobileShellUrlFromDeepLink } from './src/mobileShellDeepLink'; -import { shouldOpenInMobileShellWebView } from './src/mobileShellNavigation'; +import { + resolveMobileShellExternalUrl, + shouldOpenInMobileShellWebView, +} from './src/mobileShellNavigation'; import { buildMobileShellUrl } from './src/mobileShellUrl'; const defaultWebUrl = 'http://127.0.0.1:3000/'; @@ -107,7 +110,10 @@ export default function App() { return true; } - void Linking.openURL(request.url).catch(() => undefined); + const externalUrl = resolveMobileShellExternalUrl(request.url); + if (externalUrl) { + void Linking.openURL(externalUrl).catch(() => undefined); + } return false; }; diff --git a/apps/mobile-shell/src/mobileShellNavigation.test.ts b/apps/mobile-shell/src/mobileShellNavigation.test.ts index 46fffcf2..9d41e7fa 100644 --- a/apps/mobile-shell/src/mobileShellNavigation.test.ts +++ b/apps/mobile-shell/src/mobileShellNavigation.test.ts @@ -1,6 +1,7 @@ import { describe, expect, test } from 'vitest'; import { + resolveMobileShellExternalUrl, resolveMobileShellWebViewUrl, shouldOpenInMobileShellWebView, } from './mobileShellNavigation'; @@ -37,6 +38,21 @@ describe('shouldOpenInMobileShellWebView', () => { ); }); + test('只有允许协议能交给系统外部应用打开', () => { + expect(resolveMobileShellExternalUrl(' https://example.com/path ')).toBe( + 'https://example.com/path', + ); + expect(resolveMobileShellExternalUrl('mailto:hi@example.com')).toBe( + 'mailto:hi@example.com', + ); + expect(resolveMobileShellExternalUrl('tel:+12345678')).toBe( + 'tel:+12345678', + ); + expect(resolveMobileShellExternalUrl('javascript:alert(1)')).toBeNull(); + expect(resolveMobileShellExternalUrl('file:///etc/passwd')).toBeNull(); + expect(resolveMobileShellExternalUrl('/relative/path')).toBeNull(); + }); + test('HostBridge 主动导航只解析同源网页目标', () => { const allowedOrigin = 'https://app.genarrative.world'; diff --git a/apps/mobile-shell/src/mobileShellNavigation.ts b/apps/mobile-shell/src/mobileShellNavigation.ts index e266d90c..69c76403 100644 --- a/apps/mobile-shell/src/mobileShellNavigation.ts +++ b/apps/mobile-shell/src/mobileShellNavigation.ts @@ -1,3 +1,5 @@ +import { normalizeHostBridgeExternalUrl } from '../../../packages/shared/src/contracts/hostBridge'; + export function shouldOpenInMobileShellWebView( rawUrl: string, allowedOrigin: string, @@ -26,6 +28,10 @@ export function shouldOpenInMobileShellWebView( } } +export function resolveMobileShellExternalUrl(rawUrl: string) { + return normalizeHostBridgeExternalUrl(rawUrl); +} + export function resolveMobileShellWebViewUrl( rawUrl: string, allowedOrigin: string, diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index eec86972..5890df21 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -22,6 +22,7 @@ - 决策：移动端原生壳采用 `Expo + React Native`，桌面端壳采用 `Tauri`。两者都只作为 `native_app` 宿主壳和 HostBridge adapter，不重写现有 React H5 主站，不把固定内置玩法迁到 React Native / Rust UI，也不让 AI 生成 H5 游戏直接访问完整 HostBridge。Expo 壳通过 `react-native-webview` 承接 H5 与 native 通信，Tauri 壳通过受控 command 和 capabilities 承接桌面能力；新增能力必须先进入 HostBridge 契约和测试。 - 2026-06-17 首轮落地：新增 `packages/shared/src/contracts/hostBridge.ts`、`src/services/host-bridge/nativeAppHostBridge.ts`、`apps/mobile-shell/` 和 `apps/desktop-shell/`。壳只声明并实现真实可用能力；移动壳使用真实品牌图标资产并支持 `genarrative://`、iOS associated domain、Android app link 到同源 H5 路径，`navigation.openNativePage` 只接受同源 H5 route 并切换 WebView URL，不伪造尚未存在的原生页面，且通过 `host.events` 注入 `navigation.canGoBack` 返回栈状态事件，`share.setTarget` / `share.open` 解析统一分享目标并调用 React Native 系统分享面板，发布分享弹窗在 native_app 中通过 `share.open` 提供“系统分享”动作，失败时保留复制链接回退路径；`file.exportText` 写入 Expo 缓存文本文件后交给系统分享 / 保存面板，成功只返回文件名和字节数，`haptics.impact` 通过 Expo Haptics 承接 H5 运行时点击反馈；`app.openExternalUrl` 在 Expo 与 Tauri 两端都只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议；H5 复制服务在 native_app 中优先通过 `clipboard.writeText` 写入 Expo / Tauri 系统剪贴板，失败后再回退浏览器复制路径；H5 运行时反馈在 native_app 中优先通过 `haptics.impact` 请求真实移动端触觉，宿主不可用或 unsupported 时回退浏览器 `navigator.vibrate`；H5 主站按当前平台阶段同步 `document.title` 并通过 `app.setTitle` 请求宿主窗口标题，Tauri 壳通过主窗口 API 同步非空窗口标题，Expo 移动壳不声明该能力时静默忽略；桌面壳已通过 Tauri clipboard-manager 接入 `clipboard.writeText`，将 `navigation.openNativePage` 实现为 `https://app.genarrative.world` 同源 H5 route 的主窗口受控跳转，并将 `share.setTarget` / `share.open` 实现为复制非空分享文本到系统剪贴板；桌面 `file.exportText` 通过 Tauri dialog 插件打开系统保存对话框并由 Rust 写入文本文件，但不把 dialog / fs 插件 command 直接暴露给 H5，成功只返回文件名和字节数，用户取消返回 `cancelled`；登录、支付、原生系统分享面板等未接入真实 SDK / 插件前必须返回 unsupported 并让 H5 fallback，生产代码禁止 mock 成功。 - 2026-06-18 外链接入：H5 新增 `openHostExternalUrl()` facade，`native_app` 下会把外链归一化为允许协议的绝对 URL 后请求 `app.openExternalUrl`；ICP备案号和 RPG 资产调试原图入口已优先走宿主系统浏览器，普通浏览器和小程序保留原 `` 行为，宿主不可用或拒绝时回退浏览器外链。 +- 2026-06-18 移动壳 WebView 导航收紧：Expo WebView 自身拦截外域导航时复用 HostBridge 外链协议白名单，只把 `http:`、`https:`、`mailto:`、`tel:` 交给 `Linking.openURL`，`javascript:`、`file:`、相对异常路径等危险目标直接阻断，避免离开同源主站后仍保留完整 HostBridge。 - 影响范围：`src/services/host-bridge/`、未来 `apps/mobile-shell/`、未来 `apps/desktop-shell/`、移动端支付 / 分享 / 深链 / 推送、桌面端系统能力、AI H5 sandbox 的 GameBridge 边界。 - 验证方式：普通浏览器、小程序、Expo 壳、Tauri 壳都能返回正确 `getHostRuntime()`；未支持能力能回退 H5；固定玩法在各宿主中读取同一作品数据和运行态 snapshot；AI sandbox 无法直接调用 HostBridge；Tauri release 不允许任意远端页面调用桌面命令。 - 关联文档：`docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md`、`docs/【前端架构】宿主壳能力统一协议-2026-06-17.md`。 diff --git a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md index c27ec166..3de9b0b6 100644 --- a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md +++ b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md @@ -217,7 +217,7 @@ GameBridge 禁止： - 能力按 `capabilities` 下发，H5 根据能力决定是否展示入口或走 fallback。 - 宿主壳不得把长期 token、支付密钥或用户敏感资料回传给 H5。 - Tauri 禁止把 shell / fs 等高危插件作为默认能力暴露给主 WebView。 -- RN WebView 禁止打开任意 URL 后仍保留完整 HostBridge；跳外链应使用系统浏览器或降级能力。 +- RN WebView 禁止打开任意 URL 后仍保留完整 HostBridge；跳外链只允许 `http:`、`https:`、`mailto:`、`tel:`，并使用系统浏览器或降级能力，危险协议直接阻断。 - AI sandbox iframe 必须使用独立 CSP、`sandbox` 属性和单独 GameBridge allowlist。 ## 分阶段落地 @@ -241,7 +241,7 @@ GameBridge 禁止： - iOS / Android 深链打开作品详情、创作页和邀请码。 - 登录和支付先 fallback 到 H5；只把能力边界跑通。 -当前状态：已新增 `apps/mobile-shell/`，通过 Expo development build 运行，`react-native-webview` 加载 H5 URL 并附加 `native_app` 宿主 query。移动壳使用真实品牌图标资产，已接入 `genarrative://` scheme、iOS associated domain 和 Android app link filter，启动和运行时 deep link 只会映射到同源 H5 路径并继续附加 HostBridge 上下文，外域和危险协议回退到默认主站入口。首轮真实能力包括 `host.getRuntime`、`host.events`、`share.open`、`share.setTarget`、`navigation.openNativePage`、`navigation.canGoBack`、`app.openExternalUrl`、`clipboard.writeText`、`file.exportText`、`haptics.impact` 和 Android 返回键回退；其中 `share.setTarget` / `share.open` 会解析统一分享目标里的 `title`、`message`、`url`、`work`、`path` 或 `targetPath` 并调用 React Native 系统分享面板；发布分享弹窗在 `native_app` 中通过 `share.open` 提供“系统分享”动作，失败时保留复制链接回退路径；`navigation.openNativePage` 在 Expo 壳内只接受同源 H5 route 并切换 WebView URL，不伪造尚未存在的登录、支付或其它原生页面，`navigation.canGoBack` 由 WebView 导航状态变化实时注入 H5，`app.openExternalUrl` 只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议，ICP备案号和资产调试原图等 H5 外链入口在 `native_app` 中优先通过该能力离开 WebView 并交给系统浏览器；`clipboard.writeText` 由 H5 复制服务优先调用并写入系统剪贴板；`file.exportText` 通过 Expo 文件系统写入缓存文本文件，再交给系统分享 / 保存面板，文件名必须清洗，单次文本不超过 5 MiB，成功只返回文件名和字节数；`haptics.impact` 通过 Expo Haptics 承接运行时轻触反馈，H5 在宿主不支持时回退到浏览器 vibration。登录和支付尚未接入渠道 SDK / 原生页面时明确返回 unsupported，让 H5 fallback 承接。 +当前状态：已新增 `apps/mobile-shell/`，通过 Expo development build 运行，`react-native-webview` 加载 H5 URL 并附加 `native_app` 宿主 query。移动壳使用真实品牌图标资产，已接入 `genarrative://` scheme、iOS associated domain 和 Android app link filter，启动和运行时 deep link 只会映射到同源 H5 路径并继续附加 HostBridge 上下文，外域和危险协议回退到默认主站入口。首轮真实能力包括 `host.getRuntime`、`host.events`、`share.open`、`share.setTarget`、`navigation.openNativePage`、`navigation.canGoBack`、`app.openExternalUrl`、`clipboard.writeText`、`file.exportText`、`haptics.impact` 和 Android 返回键回退；其中 `share.setTarget` / `share.open` 会解析统一分享目标里的 `title`、`message`、`url`、`work`、`path` 或 `targetPath` 并调用 React Native 系统分享面板；发布分享弹窗在 `native_app` 中通过 `share.open` 提供“系统分享”动作，失败时保留复制链接回退路径；`navigation.openNativePage` 在 Expo 壳内只接受同源 H5 route 并切换 WebView URL，不伪造尚未存在的登录、支付或其它原生页面，`navigation.canGoBack` 由 WebView 导航状态变化实时注入 H5，WebView 自身拦截到外域导航时只会把 `http:`、`https:`、`mailto:`、`tel:` 交给系统，危险协议直接阻断；`app.openExternalUrl` 也只允许同一协议白名单，ICP备案号和资产调试原图等 H5 外链入口在 `native_app` 中优先通过该能力离开 WebView 并交给系统浏览器；`clipboard.writeText` 由 H5 复制服务优先调用并写入系统剪贴板；`file.exportText` 通过 Expo 文件系统写入缓存文本文件，再交给系统分享 / 保存面板，文件名必须清洗，单次文本不超过 5 MiB，成功只返回文件名和字节数；`haptics.impact` 通过 Expo Haptics 承接运行时轻触反馈，H5 在宿主不支持时回退到浏览器 vibration。登录和支付尚未接入渠道 SDK / 原生页面时明确返回 unsupported，让 H5 fallback 承接。 ### Phase 3：Tauri 桌面壳 MVP