# @freedomofpress/tuf-browser 中文文档

规范地址：https://npmcn.com/package/%40freedomofpress/tuf-browser/

版本：0\.3\.0
npm 元数据更新时间：2026-10-31T07:20:45.017Z
中文译文更新时间：2026-11-15T13:00:36.339Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40freedomofpress/tuf-browser
原文对照：https://npmcn.com/package/%40freedomofpress/tuf-browser/?lang=original
项目主页：https://github.com/freedomofpress/tuf-browser#readme
源码仓库：https://github.com/freedomofpress/tuf-browser

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：87.7 kB，36 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19
- 运行依赖：1 个
- 首次发布：2025-11-26T23:26:31.171Z
- 最新版本发布：2026-10-31T07:20:44.373Z
- 近 30 天下载量：112867（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

用于节点和浏览器的最小TUF客户端.

## 安装

```sh
npm install @freedomofpress/tuf-browser
```

也可以使用：`pnpm add @freedomofpress/tuf-browser`、`yarn add @freedomofpress/tuf-browser`、`bun add @freedomofpress/tuf-browser`

## README

# TUF 最小浏览器兼容性

[![Conformance](https://github.com/freedomofpress/tuf-browser/actions/workflows/conformance.yml/badge.svg)](https://github.com/sachaservan/tuf-browser/actions/workflows/conformance.yml)

最小类型脚本执行 [最新框架(TUF)](https://theupdateframework.io/) 规格,优化为浏览器兼容性.

这是一个轻量级的替代方案 [tu](https://github.com/theupdateframework/tuf-js) 侧重于浏览器环境中安全软件更新所需的TUF核心功能.

> \[叹息\]  
> 该图书馆没有收到独立的安全审计。 维护工作由志愿者进行,该项目没有得到新闻自由基金会的正式支持或认可.

## 特征

-   **TUF 核心安全**: 实施必要的TUF安全保障,包括回滚保护、密钥旋转和连贯的快照
-   **浏览器- 第一**: 为网络浏览器设计,支持本地Storage、Chrome扩展存储和文件系统后端
-   **最小依赖性**: 最大兼容性的0个外部依赖性
-   **相相竞**: 通过对辅助特性的 TUF 兼容性测试
-   **ECDSA & Ed25519 支助**: 使用Web Crypto API进行ECDSA-P256和Ed25519签名 没有原生 Ed25519 的浏览器需要应用程序调用 `installEd25519Fallback()` 从 `@freedomofpress/crypto-browser/noble` 一次开始.

## 限制

此最小执行故意省略某些 TUF 特性以优化大小和浏览器相容性 :

-   无代表团支持
-   没有RSA密钥支持(只有ECDSA和Ed25519)
-   没有镜像列表
-   没有自定义下载限制

## 使用量

```typescript
import { TUFClient } from 'tuf-browser';

// Initialize client with repository URL and root metadata
const client = new TUFClient(
  'https://repository.example.com/metadata/',
  rootMetadata,
  'my-app'
);

// Fetch and verify a target file
const targetData = await client.getTarget('path/to/target.json');
```

## 存储后端

库根据运行时环境自动选择合适的存储后端 :

| 环境 | 使用的后端 | 页:1 |
| --- | --- | --- |
| 节点.js(CLI/测试) | `FSBackend` | 将元数据和目标写入磁盘 。 要求遵守图瓦卢福林协定. |
| 浏览器扩展 | `ExtensionStorageBackend` | 使用 `browser.storage.local` API (Firefox/Chrome扩展存储). |
| 浏览器网页 | `LocalStorageBackend` | 用途 `localStorage`最小持续存储. |

## 发展

```bash
# Install dependencies
npm install

# Build the project
npm run build
```

## 实例: CLI 使用

下载 [1.root.json (英语)](https://tuf-repo-cdn.sigstore.dev/1.root.json) 或更新的 并触发新鲜.

```bash
$ node ./dist/cli.js \
    --metadata-dir /tmp/ \
    --metadata-url https://tuf-repo-cdn.sigstore.dev \
    refresh 1.root.json
```

示例输出 :

```
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/2.root.json
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/3.root.json
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/4.root.json
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/5.root.json
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/6.root.json
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/7.root.json
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/8.root.json
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/9.root.json
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/10.root.json
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/11.root.json
KeyId 7247f0dbad85b147e1863bade761243cc785dcb7aa410e7105dd3d2b61a36d2c does not match the expected 0c87432c3bf09fd99189fdc32fa5eaedf4e4a5fac7bab73fa04a2e0fc64af6f5, importing anyway the provided one for proper referencing.
KeyId 7247f0dbad85b147e1863bade761243cc785dcb7aa410e7105dd3d2b61a36d2c does not match the expected 0c87432c3bf09fd99189fdc32fa5eaedf4e4a5fac7bab73fa04a2e0fc64af6f5, importing anyway the provided one for proper referencing.
KeyId 7247f0dbad85b147e1863bade761243cc785dcb7aa410e7105dd3d2b61a36d2c does not match the expected 0c87432c3bf09fd99189fdc32fa5eaedf4e4a5fac7bab73fa04a2e0fc64af6f5, importing anyway the provided one for proper referencing.
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/12.root.json
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/13.root.json
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/14.root.json
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/timestamp.json
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/162.snapshot.json
[TUF] Fetching https://tuf-repo-cdn.sigstore.dev/13.targets.json
```

CLI 行为遵循 TUF 客户端的规格 [遵守规定](https://github.com/theupdateframework/tuf-conformance) 套间.

**说明**:CLI是符合性测试的最低限度参考执行. 它执行核心 `init`, (中文(简体) ), `refresh`,以及 `download` 命令但缺少一些命令(例如, `metadata`某些符合性测试要求。 用于生产、进口和使用 `TUFClient` 阶级直接而不是依赖CLI.

## 运行 TUF 合规测试套件

需要Python 3.11和虚拟env.

```bash
git clone https://github.com/theupdateframework/tuf-conformance
cd tuf-conformance
make env/pyvenv.cfg
./env/bin/pytest -v tuf_conformance \
   --entrypoint "/usr/bin/node /tuf-browser/dist/cli.js" \
   --repository-dump-dir /tmp/
```

## 遵约

在108项TUF合规性测试中,这项实施工作通过了75项。 其余的测试涵盖有意不支持的特性(代表团,RSA密钥).

### 已知问题和待办事宜

采用了TUF的核心功能(元数据核查、签名核对、回滚保护、用SHA-256/SHA-512支持的散列核查)。 其余合格测试失败:

-   **根元数据字节保存** (单位:千美元)`test_metadata_bytes_match`(中文(简体) )
    
    Root 元数据在写入时重新序列化([页:1](https://npmcn.com/package/%40freedomofpress/tuf-browser/src/tuf.ts#L236) 用途 `setInCache` → `backend.write`),而其他角色则正确使用 `writeRaw` 用于保存字节.
    
-   **快速恢复** (3次测试 `test_rollback.py`(中文(简体) )
    
    部分执行: 缓存元数据在键旋转时被清除( Q)[图:245 - 267](https://npmcn.com/package/%40freedomofpress/tuf-browser/src/tuf.ts#L245-L267)) (中文(简体) ). 该代码严格拒绝版本降级,而不是尝试恢复.
    
-   **其他测试失败** (~10个剩余测试)
    
    各种失败与文件下载,静态寄存器,和边缘大小写有关.
    

## 许可证

麻省理工学院执照 - 看 [自由主义](https://npmcn.com/package/%40freedomofpress/tuf-browser/LICENSE) 详细文件。 本套件的几分部分包含代码来自 [缩写](https://github.com/sigstore/sigstore-js) 并获得Apache许可证2.0许可。 这些章节在相应的源文件头中被清楚地标明.

## 承认

这个项目的基础是: [TUF 规格](https://theupdateframework.github.io/specification/v1.0.33/index.html) 并改编自 [tu](https://github.com/theupdateframework/tuf-js) 财务报告和审定财务报表 [缩写](https://github.com/sigstore/sigstore-js)。 。 。 .

## 常见问题

### @freedomofpress/tuf-browser 是什么？

用于节点和浏览器的最小TUF客户端\.

### 如何安装 @freedomofpress/tuf-browser？

在项目目录运行 npm install @freedomofpress/tuf-browser，或使用 pnpm add / yarn add / bun add。

### @freedomofpress/tuf-browser 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @freedomofpress/tuf-browser 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @freedomofpress/tuf-browser 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @freedomofpress/tuf-browser 可以商用吗？

@freedomofpress/tuf-browser 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @freedomofpress/tuf-browser 的下载量有多少？

根据 npm 官方下载统计，@freedomofpress/tuf-browser 在 2026/10/16 – 2026/11/14 这 30 天内被下载 112,867 次，日均约 3,762 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @freedomofpress/tuf-browser 还在维护吗？

最新版本 0\.3\.0 发布于 2026/10/31（15 天前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2025/11/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。