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

收紧窗口标题载荷边界

Browse Source 
将 app.setTitle 标题长度和控制字符规则提升到共享 HostBridge 契约

让 H5 facade 和 Tauri 壳按共享窗口标题边界归一化载荷

增加标题边界测试和三端壳总门禁反查

同步宿主壳协议文档和共享决策记录
This commit is contained in:
段舒康
2026-06-19 15:34:37 +08:00
parent 4b269c7bc2
commit 64f496d091
9 changed files with 72 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/desktop-shell/scripts/check-config.mjs
+8
View File
@@ -1130,6 +1130,10 @@ const sharedHostBridgePayloadLimits = {
sharedContractSource,
'HOST_BRIDGE_BADGE_COUNT_MAX',
),
HOST_BRIDGE_APP_TITLE_MAX_LENGTH: extractTsNumberConst(
sharedContractSource,
'HOST_BRIDGE_APP_TITLE_MAX_LENGTH',
),
HOST_BRIDGE_CLIPBOARD_TEXT_MAX_LENGTH: extractTsNumberConst(
sharedContractSource,
'HOST_BRIDGE_CLIPBOARD_TEXT_MAX_LENGTH',
@@ -1192,6 +1196,10 @@ const desktopHostBridgePayloadLimits = {
rustHostSource,
'BADGE_COUNT_MAX',
),
HOST_BRIDGE_APP_TITLE_MAX_LENGTH: extractRustNumberConst(
rustHostSource,
'WINDOW_TITLE_MAX_LENGTH',
),
HOST_BRIDGE_CLIPBOARD_TEXT_MAX_LENGTH: extractRustNumberConst(
rustHostSource,
'CLIPBOARD_TEXT_MAX_LENGTH',
apps/desktop-shell/src-tauri/src/host_bridge/dispatch.rs
+2 -1
View File
@@ -25,6 +25,7 @@ const BADGE_COUNT_MAX: i64 = 99999;
const LOCAL_NOTIFICATION_TITLE_MAX_LENGTH: usize = 80;
const LOCAL_NOTIFICATION_BODY_MAX_LENGTH: usize = 240;
const CLIPBOARD_TEXT_MAX_LENGTH: usize = 100000;
const WINDOW_TITLE_MAX_LENGTH: usize = 80;
fn normalize_window_title(raw_title: &str) -> Option<String> {
let title = raw_title.trim();
@@ -32,7 +33,7 @@ fn normalize_window_title(raw_title: &str) -> Option<String> {
return None;
}
Some(title.chars().take(80).collect())
Some(title.chars().take(WINDOW_TITLE_MAX_LENGTH).collect())
}
fn badge_count_payload(request: &HostBridgeRequest) -> Result<Option<i64>, HostBridgeResponse> {
docs/project-memory/shared-memory/decision-log.md
+1 -1
View File
@@ -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 并完成上限校验，无法拿到可信大小时直接拒绝导入。`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 长度、角标上限、窗口标题长度、剪贴板文本长度、触觉反馈 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`、`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`。
docs/【前端架构】宿主壳能力统一协议-2026-06-17.md
+1 -1
View File
@@ -65,7 +65,7 @@ Tauri 桌面壳启动时必须按 `label="main"` 解析 `tauri.conf.json` 主窗
- `readHostClipboardText()`：原生 App 宿主的受控剪贴板读取入口。H5 只能读取纯文本结果，宿主返回内容会按 HostBridge 契约限制到 100000 字符；Expo 移动壳通过 `expo-clipboard` 读取系统剪贴板文本，Tauri 桌面壳通过 Rust 侧 `clipboard-manager` 读取系统剪贴板文本。该能力不读取图片、HTML、文件列表或剪贴板监听事件，不把 Tauri / Expo 剪贴板插件 API 直接暴露给 H5；宿主未声明或读取失败时由 H5 视作失败并保留原流程。个人中心的邀请码和兑换码弹窗只在宿主声明 `clipboard.readText` 时显示“粘贴”，读取到的纯文本只填入现有输入框，不自动提交、不代表兑换成功。
- `requestHostHapticsImpact()`：原生 App 宿主的受控触觉反馈入口。Expo 移动壳通过 `haptics.impact` 调用 Expo Haptics，只接受 `light`、`medium`、`heavy` 三档 impact style，缺省为 `light`；H5 facade 发起请求前先按共享清单归一化 style，未知值不发往宿主，移动壳仍必须二次拒绝未知值且不触发设备反馈；H5 运行时点击反馈在 `native_app` 中优先请求宿主触觉，宿主不可用、拒绝或返回 unsupported 时继续回退到浏览器 `navigator.vibrate`。
- `showHostLocalNotification()`：原生 App 宿主的受控即时本地通知入口。H5 只能传必填 `title` 和可选 `body`，两者都会去除首尾空白、折叠普通空白、限制长度并拒绝控制字符；Expo 移动壳通过 `expo-notifications` 请求通知权限、创建 Android 本地通知 channel 并立刻调度本地通知，Android channel id 固定为共享契约 `HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID`；Tauri 桌面壳通过 Rust 侧 `tauri-plugin-notification` 先检查系统通知权限，处于 prompt 状态时只在 Rust 侧请求一次权限，最终授权后才发送系统通知。该能力不包含远程推送、token 注册、定时提醒、后台远程通知或任意通知插件透传，宿主未声明、权限拒绝或系统失败时由 H5 视作失败并继续主流程。当前 H5 只在现有草稿生成任务收口为完成或失败时请求即时本地通知；通知按草稿来源去重，同一草稿重新进入生成中后才允许再次通知，不改变队列状态、弹窗、作品架或后端裁决。平台壳同步层必须通过真实 `host_bridge_request` transport 测到 `notification.showLocal` 请求，不能只测模型文案或替换 facade。
- `setHostAppTitle()`：原生 App 宿主的受控窗口标题入口。H5 主站会按当前平台阶段先同步 `document.title`，再通过 `app.setTitle` 请求宿主窗口标题同步；Tauri 桌面壳支持该能力，Expo 移动壳不声明时静默忽略。
- `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。宿主不可用或拒绝时回退浏览器外链行为，普通浏览器和小程序保持原有 `<a>` 语义。H5 支付链接和微信 OAuth 登录授权 URL 也走该入口：原生壳未声明真实 `payment.request` / `auth.requestLogin` 前，微信 H5 支付 URL 和后端返回的微信登录授权 URL 优先交给宿主系统浏览器，宿主未处理时才回退当前 WebView 跳转；不得把 H5 支付或网页登录伪装成已完成的原生支付 / 原生登录。
packages/shared/src/contracts/hostBridge.test.ts
+12
View File
@@ -32,6 +32,7 @@ import {
isHostBridgeMethod,
isHostBridgeCapability,
isHostBridgeEventName,
normalizeHostBridgeAppTitle,
normalizeHostBridgeBadgeCount,
normalizeHostBridgeClipboardText,
normalizeHostBridgeColorScheme,
@@ -296,6 +297,17 @@ describe('HostBridge shared contract helpers', () => {
expect(normalizeHostBridgeClipboardText(null)).toBeNull();
});
test('归一化宿主窗口标题', () => {
expect(normalizeHostBridgeAppTitle(' 拼图 - 陶泥儿 ')).toEqual({
title: '拼图 - 陶泥儿',
});
expect(normalizeHostBridgeAppTitle('')).toBeNull();
expect(normalizeHostBridgeAppTitle('拼图\n陶泥儿')).toBeNull();
expect(normalizeHostBridgeAppTitle('a'.repeat(90))).toEqual({
title: 'a'.repeat(80),
});
});
test('归一化宿主二维码扫码结果', () => {
expect(normalizeHostBridgeQrCodeValue(' https://example.com/a ')).toEqual({
value: 'https://example.com/a',
packages/shared/src/contracts/hostBridge.ts
+17
View File
@@ -382,6 +382,23 @@ export type SetTitlePayload = {
title: string;
};
export const HOST_BRIDGE_APP_TITLE_MAX_LENGTH = 80;
export function normalizeHostBridgeAppTitle(rawTitle: unknown): SetTitlePayload | null {
if (typeof rawTitle !== 'string') {
return null;
}
const title = rawTitle.trim();
if (!title || hasHostBridgeControlCharacter(title)) {
return null;
}
return {
title: title.slice(0, HOST_BRIDGE_APP_TITLE_MAX_LENGTH),
};
}
export type SetBadgeCountPayload = {
count: number;
};
scripts/check-native-shells.mjs
+13
View File
@@ -979,6 +979,7 @@ function assertH5HostBridgePayloadBoundaries() {
'HOST_BRIDGE_RUNTIME_REFRESH_TIMEOUT_MS',
'HOST_BRIDGE_USER_INTERACTION_TIMEOUT_MS',
'HOST_BRIDGE_SCANNER_TIMEOUT_MS',
'HOST_BRIDGE_APP_TITLE_MAX_LENGTH',
]) {
if (!h5HostBridgeSource.includes(`${sharedBoundary},`)) {
throw new Error(
@@ -1052,6 +1053,18 @@ function assertH5HostBridgePayloadBoundaries() {
'H5 HostBridge facade must normalize haptics.impact payloads with the shared style boundary',
);
}
if (
!h5HostBridgeSource.includes(
'const normalizedTitle = normalizeHostBridgeAppTitle(title);',
) ||
!h5HostBridgeSource.includes(
"return await requestNativeHostBoolean('app.setTitle', normalizedTitle);",
)
) {
throw new Error(
'H5 HostBridge facade must normalize app.setTitle payloads with the shared title boundary',
);
}
}
function assertH5NativeAppTransportTimeoutBoundaries() {
src/services/host-bridge/hostBridge.test.ts
+14
View File
@@ -1025,6 +1025,12 @@ describe('hostBridge', () => {
await expect(setHostAppTitle({ title: ' 拼图 - 陶泥儿 ' })).resolves.toBe(
true,
);
await expect(
setHostAppTitle({ title: 'a'.repeat(90) }),
).resolves.toBe(true);
await expect(setHostAppTitle({ title: '拼图\n陶泥儿' })).resolves.toBe(
false,
);
await expect(setHostAppBadgeCount({ count: 7 })).resolves.toBe(true);
await expect(getHostNetworkStatus()).resolves.toEqual({
isConnected: true,
@@ -1167,6 +1173,14 @@ describe('hostBridge', () => {
},
}),
});
expect(invoke).toHaveBeenCalledWith('host_bridge_request', {
request: expect.objectContaining({
method: 'app.setTitle',
payload: {
title: 'a'.repeat(80),
},
}),
});
expect(invoke).toHaveBeenCalledWith('host_bridge_request', {
request: expect.objectContaining({
method: 'app.setBadgeCount',
src/services/host-bridge/hostBridge.ts
+4 -4
View File
@@ -26,6 +26,7 @@ import type {
} from '../../../packages/shared/src/contracts/hostBridge';
import {
HOST_BRIDGE_AUDIO_MIME_TYPES,
HOST_BRIDGE_APP_TITLE_MAX_LENGTH,
HOST_BRIDGE_DOCUMENT_MIME_TYPES,
HOST_BRIDGE_IMAGE_MIME_TYPES,
HOST_BRIDGE_NATIVE_APP_QUERY,
@@ -37,6 +38,7 @@ import {
HOST_BRIDGE_WECHAT_MINI_PROGRAM_SOURCE_QUERY,
isHostBridgeCapability,
normalizeHostBridgeBadgeCount,
normalizeHostBridgeAppTitle,
normalizeHostBridgeClipboardText,
normalizeHostBridgeColorScheme,
normalizeHostBridgeConnectionType,
@@ -1145,15 +1147,13 @@ export async function showHostLocalNotification(
}
export async function setHostAppTitle({ title }: HostAppTitleRequest) {
const normalizedTitle = title.trim();
const normalizedTitle = normalizeHostBridgeAppTitle(title);
if (!normalizedTitle || !canUseNativeHostCapability('app.setTitle')) {
return false;
}
try {
return await requestNativeHostBoolean('app.setTitle', {
title: normalizedTitle,
});
return await requestNativeHostBoolean('app.setTitle', normalizedTitle);
} catch {
return false;
}