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

收紧媒体导出载荷边界

Browse Source 
将图片和音频导出载荷预校验提升到共享 HostBridge 契约
让 H5 facade 按共享媒体导出边界归一化文件名、MIME 和 base64 载荷
保留 Expo 与 Tauri 壳对真实字节和 MIME 的二次校验
增加媒体导出载荷测试和三端壳总门禁反查
同步宿主壳协议文档和共享决策记录
This commit is contained in:
段舒康
2026-06-19 16:18:54 +08:00
parent 14da1a7e12
commit 71510ef797
7 changed files with 187 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
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 长度、角标上限、窗口标题长度、外链 URL payload、分享 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 并完成上限校验，无法拿到可信大小时直接拒绝导入。`share.open` 必须通过共享 `normalizeHostBridgeShareOpenPayload()` 把 `url`、`href`、`path`、`targetPath` 和 `work` 归一到公开 H5 同源 URL，H5 facade 和 Expo 移动壳都执行该边界，Tauri 壳用 Rust URL parser 镜像同一规则。`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` 是 HostBridge 载荷边界的声明来源，导出文本 / 图片 / 音频 MIME 清单、文档导入 MIME 清单、导入 / 导出字节上限、导出文件名 fallback / 长度上限、request id 长度、角标上限、窗口标题长度、外链 URL payload、分享 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 并完成上限校验，无法拿到可信大小时直接拒绝导入。`share.open` 必须通过共享 `normalizeHostBridgeShareOpenPayload()` 把 `url`、`href`、`path`、`targetPath` 和 `work` 归一到公开 H5 同源 URL，H5 facade 和 Expo 移动壳都执行该边界，Tauri 壳用 Rust URL parser 镜像同一规则。`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 通过文本导出通道伪装落盘；`file.exportImage` / `file.exportAudio` 必须在 H5 facade 发起请求前分别通过 `normalizeHostBridgeExportImagePayload()` / `normalizeHostBridgeExportAudioPayload()` 预校验文件名、MIME、base64 和共享导出上限，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
+2 -2
View File
File diff suppressed because one or more lines are too long
packages/shared/src/contracts/hostBridge.test.ts
+41
View File
@@ -37,7 +37,9 @@ import {
normalizeHostBridgeClipboardText,
normalizeHostBridgeColorScheme,
normalizeHostBridgeConnectionType,
normalizeHostBridgeExportAudioPayload,
normalizeHostBridgeExportFileName,
normalizeHostBridgeExportImagePayload,
normalizeHostBridgeExternalUrl,
normalizeHostBridgeExternalUrlPayload,
normalizeHostBridgeHapticsImpactStyle,
@@ -349,6 +351,45 @@ describe('HostBridge shared contract helpers', () => {
expect(HOST_BRIDGE_IMPORT_DOCUMENT_MAX_BYTES).toBe(5 * 1024 * 1024);
});
test('归一化宿主图片和音频导出载荷', () => {
expect(
normalizeHostBridgeExportImagePayload({
fileName: ' ../分享:卡?.png ',
base64Data: ' c2hhcmU= ',
mimeType: 'image/png',
}),
).toEqual({
fileName: '分享-卡-.png',
base64Data: 'c2hhcmU=',
mimeType: 'image/png',
});
expect(
normalizeHostBridgeExportAudioPayload({
fileName: '敲击音效.wav',
base64Data: ' YXVkaW8= ',
mimeType: 'audio/wav',
}),
).toEqual({
fileName: '敲击音效.wav',
base64Data: 'YXVkaW8=',
mimeType: 'audio/wav',
});
expect(
normalizeHostBridgeExportImagePayload({
fileName: 'bad.gif',
base64Data: 'c2hhcmU=',
mimeType: 'image/gif',
}),
).toBeNull();
expect(
normalizeHostBridgeExportAudioPayload({
fileName: 'empty.wav',
base64Data: ' ',
mimeType: 'audio/wav',
}),
).toBeNull();
});
test('归一化宿主本地通知内容', () => {
expect(
normalizeHostBridgeLocalNotification({
packages/shared/src/contracts/hostBridge.ts
+82
View File
@@ -573,6 +573,10 @@ export const HOST_BRIDGE_IMAGE_MIME_TYPES = [
'image/webp',
] as const satisfies readonly HostBridgeImageMimeType[];
const HOST_BRIDGE_IMAGE_MIME_TYPE_SET = new Set<HostBridgeImageMimeType>(
HOST_BRIDGE_IMAGE_MIME_TYPES,
);
export type FileImportImageResult = {
action: 'selected' | 'dropped' | 'captured';
fileName: string;
@@ -625,6 +629,10 @@ export const HOST_BRIDGE_AUDIO_MIME_TYPES = [
'audio/webm',
] as const satisfies readonly HostBridgeAudioMimeType[];
const HOST_BRIDGE_AUDIO_MIME_TYPE_SET = new Set<HostBridgeAudioMimeType>(
HOST_BRIDGE_AUDIO_MIME_TYPES,
);
export type FileImportAudioResult = {
action: 'selected';
fileName: string;
@@ -653,6 +661,80 @@ export const HOST_BRIDGE_IMPORT_IMAGE_MAX_BYTES = 10 * 1024 * 1024;
export const HOST_BRIDGE_EXPORT_AUDIO_MAX_BYTES = 20 * 1024 * 1024;
export const HOST_BRIDGE_IMPORT_AUDIO_MAX_BYTES = 20 * 1024 * 1024;
function normalizeHostBridgeBase64Data(rawData: unknown) {
if (typeof rawData !== 'string') {
return null;
}
const base64Data = rawData.trim();
if (!base64Data || hasHostBridgeControlCharacter(base64Data)) {
return null;
}
return base64Data;
}
function estimateHostBridgeBase64Bytes(base64Data: string) {
const normalizedLength = base64Data.replace(/\s+/g, '').length;
return Math.ceil((normalizedLength * 3) / 4);
}
export function normalizeHostBridgeExportImagePayload(
payload: unknown,
): FileExportImagePayload | null {
if (!payload || typeof payload !== 'object') {
return null;
}
const candidate = payload as Partial<FileExportImagePayload>;
const mimeType = candidate.mimeType as HostBridgeImageMimeType;
if (!HOST_BRIDGE_IMAGE_MIME_TYPE_SET.has(mimeType)) {
return null;
}
const base64Data = normalizeHostBridgeBase64Data(candidate.base64Data);
if (
!base64Data ||
estimateHostBridgeBase64Bytes(base64Data) > HOST_BRIDGE_EXPORT_IMAGE_MAX_BYTES
) {
return null;
}
return {
fileName: normalizeHostBridgeExportFileName(candidate.fileName),
base64Data,
mimeType,
};
}
export function normalizeHostBridgeExportAudioPayload(
payload: unknown,
): FileExportAudioPayload | null {
if (!payload || typeof payload !== 'object') {
return null;
}
const candidate = payload as Partial<FileExportAudioPayload>;
const mimeType = candidate.mimeType as HostBridgeAudioMimeType;
if (!HOST_BRIDGE_AUDIO_MIME_TYPE_SET.has(mimeType)) {
return null;
}
const base64Data = normalizeHostBridgeBase64Data(candidate.base64Data);
if (
!base64Data ||
estimateHostBridgeBase64Bytes(base64Data) > HOST_BRIDGE_EXPORT_AUDIO_MAX_BYTES
) {
return null;
}
return {
fileName: normalizeHostBridgeExportFileName(candidate.fileName),
base64Data,
mimeType,
};
}
export const HOST_BRIDGE_HAPTICS_IMPACT_STYLES = [
'light',
'medium',
scripts/check-native-shells.mjs
+24
View File
@@ -1060,6 +1060,30 @@ function assertH5HostBridgePayloadBoundaries() {
'H5 HostBridge facade must normalize share.open payloads with the shared share boundary',
);
}
if (
!h5HostBridgeSource.includes(
'const normalizedPayload = normalizeHostBridgeExportImagePayload(params);',
) ||
!h5HostBridgeSource.includes(
"'file.exportImage',\n normalizedPayload,",
)
) {
throw new Error(
'H5 HostBridge facade must normalize file.exportImage payloads with the shared image export boundary',
);
}
if (
!h5HostBridgeSource.includes(
'const normalizedPayload = normalizeHostBridgeExportAudioPayload(params);',
) ||
!h5HostBridgeSource.includes(
"'file.exportAudio',\n normalizedPayload,",
)
) {
throw new Error(
'H5 HostBridge facade must normalize file.exportAudio payloads with the shared audio export boundary',
);
}
if (
!h5HostBridgeSource.includes(
'const clipboardText = normalizeHostBridgeClipboardText(text);',
src/services/host-bridge/hostBridge.test.ts
+23 -3
View File
@@ -1053,8 +1053,8 @@ describe('hostBridge', () => {
).resolves.toBe(false);
await expect(
exportHostImageFile({
fileName: '分享卡.png',
base64Data: 'c2hhcmUtY2FyZA==',
fileName: ' ../分享:卡?.png ',
base64Data: ' c2hhcmUtY2FyZA== ',
mimeType: 'image/png',
}),
).resolves.toBe(true);
@@ -1220,7 +1220,7 @@ describe('hostBridge', () => {
request: expect.objectContaining({
method: 'file.exportImage',
payload: {
fileName: '分享卡.png',
fileName: '分享-卡-.png',
base64Data: 'c2hhcmUtY2FyZA==',
mimeType: 'image/png',
},
@@ -1536,6 +1536,16 @@ describe('hostBridge', () => {
timeoutMs: HOST_BRIDGE_USER_INTERACTION_TIMEOUT_MS,
}),
});
invoke.mockClear();
await expect(
exportHostImageFile({
fileName: 'bad.gif',
base64Data: 'c2hhcmUtY2FyZA==',
mimeType: 'image/gif' as 'image/png',
}),
).resolves.toBe(false);
expect(invoke).not.toHaveBeenCalled();
});
test('原生 App 宿主不支持文本导出时回退 H5', async () => {
@@ -1897,6 +1907,16 @@ describe('hostBridge', () => {
timeoutMs: HOST_BRIDGE_USER_INTERACTION_TIMEOUT_MS,
}),
});
invoke.mockClear();
await expect(
exportHostAudioFile({
fileName: 'empty.wav',
base64Data: ' ',
mimeType: 'audio/wav',
}),
).resolves.toBe(false);
expect(invoke).not.toHaveBeenCalled();
});
test('原生 App 宿主取消导入音频时回退为 false', async () => {
src/services/host-bridge/hostBridge.ts
+14 -2
View File
@@ -43,6 +43,8 @@ import {
normalizeHostBridgeClipboardText,
normalizeHostBridgeColorScheme,
normalizeHostBridgeConnectionType,
normalizeHostBridgeExportAudioPayload,
normalizeHostBridgeExportImagePayload,
normalizeHostBridgeExternalUrlPayload,
normalizeHostBridgeHapticsImpactStyle,
normalizeHostBridgeLifecycleState,
@@ -854,10 +856,15 @@ export async function exportHostImageFile(
return false;
}
const normalizedPayload = normalizeHostBridgeExportImagePayload(params);
if (!normalizedPayload) {
return false;
}
try {
return await requestNativeAppHostBridge<FileExportImageResult>(
'file.exportImage',
params,
normalizedPayload,
{ timeoutMs: HOST_BRIDGE_USER_INTERACTION_TIMEOUT_MS },
);
} catch (error) {
@@ -875,10 +882,15 @@ export async function exportHostAudioFile(
return false;
}
const normalizedPayload = normalizeHostBridgeExportAudioPayload(params);
if (!normalizedPayload) {
return false;
}
try {
return await requestNativeAppHostBridge<FileExportAudioResult>(
'file.exportAudio',
params,
normalizedPayload,
{ timeoutMs: HOST_BRIDGE_USER_INTERACTION_TIMEOUT_MS },
);
} catch (error) {