VerifyFetch

你的用户下载了一个 4GB 的 AI 模型，但在 3.8GB 时失败了。
VerifyFetch 会从 3.8GB 处恢复并验证每一个字节。

``` npm install verifyfetch ``` ``` import { verifyFetch } from 'verifyfetch'; const response = await verifyFetch('/model.bin', { sri: 'sha256-uU0nuZNNPgilLlLX2n2r+sSE7+N6U4DukIj3rOLvzek=' }); ``` **就是这样。** 如果哈希值不匹配，它会抛出异常。你的用户将得到保护。 ## 为什么需要它？ 在浏览器中加载大文件存在很多问题： - **内存爆炸** — `crypto.subtle.digest()` 会缓冲整个文件。4GB 模型 = 4GB 内存 = 崩溃。 - **无法恢复** — 网络在 3.8GB 时断开了？只能从零开始重新下载。 - **静默损坏** — CDN 提供了错误的数据？直到推理输出垃圾结果你才会发现。 - **供应链攻击** — [polyfill.io](https://sansec.io/research/polyfill-supply-chain-attack) 危及了超过 10 万个网站。 VerifyFetch 修复了所有这些问题：**在恒定内存下进行流式验证，支持可恢复下载，以及快速的损坏检测。** ## 结合 Transformers.js 使用 ``` npm install @verifyfetch/transformers @huggingface/transformers ``` **1. 为你的模型生成哈希值：** ``` npx @verifyfetch/cli hash-model Xenova/distilbert-base-uncased-finetuned-sst-2-english ``` **2. 使用它：** ``` import { verifiedPipeline } from '@verifyfetch/transformers'; const classifier = await verifiedPipeline( 'sentiment-analysis', 'Xenova/distilbert-base-uncased-finetuned-sst-2-english', { manifestUrl: '/models.vf.manifest.json' } ); const result = await classifier('I love this!'); // [{ label: 'POSITIVE', score: 0.99 }] ``` 每个文件都会经过验证且支持断点续传。如果连接中断，它会从中断的地方继续下载。 ## 结合 WebLLM 使用 ``` npm install @verifyfetch/webllm @mlc-ai/web-llm ``` ``` import { createVerifiedMLCEngine } from '@verifyfetch/webllm'; const engine = await createVerifiedMLCEngine('Phi-3-mini-4k-instruct-q4f16_1-MLC', { manifestUrl: '/models.vf.manifest.json', onProgress: ({ file, percent, resumed }) => { console.log(`${file}: ${percent}%${resumed ? ' (resumed)' : ''}`); } }); ``` ## 处理任意文件 ``` import { verifyFetchResumable } from 'verifyfetch'; const model = await verifyFetchResumable('/phi-3-mini.gguf', { chunked: manifest.artifacts['/phi-3-mini.gguf'].chunked, persist: true, onProgress: ({ percent, resumed }) => { console.log(`${percent}%${resumed ? ' (resumed)' : ''}`); } }); ``` 或者使用 **Service Worker** 来验证每一次 fetch，无需修改任何代码： ``` // sw.js import { createVerifyWorker } from 'verifyfetch/worker'; createVerifyWorker({ manifestUrl: '/vf.manifest.json', include: ['*.wasm', '*.bin', '*.onnx', '*.safetensors'], }); ``` ``` // app.js — no changes needed const model = await fetch('/model.bin'); // automatically verified ``` ## 工作原理 1. 你为文件生成 SHA-256 哈希值（CLI 只需一个命令即可完成） 2. 哈希值存储在一个 manifest JSON 文件中，随你的应用一起发布 3. VerifyFetch 分块下载文件，并在每个数据块到达时进行验证 4. 如果某个数据块损坏，它会立即停止 —— 不会浪费带宽 5. 如果连接中断，它会通过 IndexedDB 从上一个已验证的数据块处恢复 6. 无论文件大小如何，内存占用始终保持不变（约 2MB） ## 软件包 | 软件包 | 描述 | |---------|-------------| | [`verifyfetch`](https://www.npmjs.com/package/verifyfetch) | 核心库 —— 已验证的 fetch、流式传输、可恢复下载 | | [`@verifyfetch/transformers`](https://www.npmjs.com/package/@verifyfetch/transformers) | 开箱即用的 Transformers.js 集成 | | [`@verifyfetch/webllm`](https://www.npmjs.com/package/@verifyfetch/webllm) | 开箱即用的 WebLLM 集成 | | [`@verifyfetch/cli`](https://www.npmjs.com/package/@verifyfetch/cli) | 用于生成哈希值和 manifest 的 CLI | | [`@verifyfetch/manifests`](https://www.npmjs.com/package/@verifyfetch/manifests) | 流行模型的预计算哈希值 |

完整 API 参考

### `verifyFetch(url, options)` ``` const response = await verifyFetch('/file.bin', { sri: 'sha256-...', onFail: 'block', // 'block' | 'warn' | { fallbackUrl } onProgress: (bytes, total) => {}, }); ``` ### `verifyFetchStream(url, options)` 在恒定内存下进行流式验证。 ``` const { stream, verified } = await verifyFetchStream('/file.bin', { sri: 'sha256-...', }); for await (const chunk of stream) { await processChunk(chunk); } await verified; // throws if verification fails ``` ### `verifyFetchResumable(url, options)` 通过 IndexedDB 进行带有分块验证的可恢复下载。 ``` const result = await verifyFetchResumable('/model.bin', { chunked: manifest.artifacts['/model.bin'].chunked, persist: true, onProgress: ({ bytesVerified, totalBytes, resumed, speed, eta }) => {}, }); ``` ### `verifyFetchFromSources(sri, path, options)` 多 CDN 故障转移。 ``` const response = await verifyFetchFromSources('sha256-...', '/file.bin', { sources: ['https://cdn1.com', 'https://cdn2.com'], strategy: 'race', // 'sequential' | 'race' | 'fastest' }); ``` ### `createVerifyWorker(options)` (Service Worker) ``` createVerifyWorker({ manifestUrl: '/vf.manifest.json', include: ['*.wasm', '*.bin', '*.onnx'], onFail: 'block', }); ``` ### CLI ``` npx verifyfetch sign # Generate SRI hashes npx verifyfetch sign --chunked # With chunk hashes npx verifyfetch hash-model # Hash a HuggingFace model npx verifyfetch enforce --manifest vf.manifest.json # Verify in CI ```

安全模型

**可防范：** CDN 被入侵、MITM 攻击、意外数据损坏、供应链攻击。 **无法防范：** 构建管道被入侵（你发布了错误的哈希值）。为此，请在 CI 中使用 `verifyfetch enforce`。

参与贡献

``` pnpm install pnpm build:wasm # Requires Rust pnpm build pnpm test # 437 tests ```

文档 · GitHub · 更新日志

_{Apache-2.0 许可证}

标签：AI模型部署, CDN安全, CMS安全, DLL 劫持, JavaScript, LLM, npm包, SHA-256, SRI, Transformers.js, TypeScript, Unmanaged PE, Web API, WebLLM, 前端, 前端安全, 可视化界面, 哈希校验, 大文件下载, 大语言模型, 安全插件, 开源库, 搜索引擎爬虫, 数据完整性校验, 断点续传, 浏览器存储, 自动化攻击, 防篡改