# @flun/webauthn-server 中文文档

规范地址：https://npmcn.com/package/%40flun/webauthn-server/

版本：2\.1\.16
npm 元数据更新时间：2026-11-13T12:36:56.056Z
中文译文更新时间：2026-11-15T23:39:20.203Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：296 kB，71 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：9 个
- 首次发布：2026-04-30T06:21:05.498Z
- 最新版本发布：2026-11-13T12:36:55.876Z
- 近 30 天下载量：1997（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：43（近 12 个月 43 个）

## 中文简介

节点.js → WebAuthn/Passkey →; 19. TypeScript → CBOR →; 2;

## 安装

```sh
npm install @flun/webauthn-server
```

也可以使用：`pnpm add @flun/webauthn-server`、`yarn add @flun/webauthn-server`、`bun add @flun/webauthn-server`

## README

# @flun/webauthn-server

![WebAuthn](https://img.shields.io/badge/WebAuthn-Simplified-blueviolet?style=for-the-badge&logo=WebAuthn) [![npm (scoped)](https://img.shields.io/npm/v/@flun/webauthn-server?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@flun/webauthn-server)

## 简介

**@flun/webauthn-server** 是一个专为 Node.js 环境设计的 WebAuthn(含 Passkeys)服务端工具库,采用 TypeScript 编写,提供对证书、 密钥及 CBOR 编码的完整处理能力;它简化了 FIDO2/Passkey 身份验证后端的构建过程,支持当前所有主流的 WebAuthn 认证格式; 并且支持Windows下优先调用底层Windows hello 注册/认证(避免环境干扰与安全);

> **模块规范**:本包使用 ESM 模块编写;要求 Node.js ≥ 22.12.0, 若使用低版本 Node 则需通过 `import` 语法导入(不建议在低于 22.12.0 的环境中使用 `require()`);

* * *

## 特性

-   **WebAuthn 注册与认证** 提供 `generateRegistrationOptions` / `verifyRegistrationResponse` 和 `generateAuthenticationOptions` / `verifyAuthenticationResponse` 两对核心方法,完整实现 WebAuthn 后端逻辑;
    
-   **全格式证明支持** 支持 `packed`、`fido-u2f`、`android-safetynet`、`android-key`、`tpm`、`apple`、`none` 等所有标准认证格式; 每种格式的验证逻辑均已内置,无需额外配置;
    
-   **元数据服务 (MDS)** 内置 `MetadataService` 可下载并解析 FIDO 联盟的元数据 BLOB,验证认证器真伪与状态;
    
-   **证书链验证** 提供证书路径验证、吊销检查、X.509 解析等工具;
    
-   **丰富的辅助工具** 通过 `@flun/webauthn-server/helpers` 子路径导出大量底层工具:Base64URL 编解码、COSE ↔ PKCS 转换、authData 解析、 签名验证等;
    
-   **Windows hello 底层调用** Windows下优先调用底层Windows hello 注册/认证(避免环境干扰与安全);
    

* * *

## 包目录结构

随包发布的文件:

```
@flun/webauthn-server/
├── index.js           库入口,聚合导出各模块
├── index.d.ts         类型声明
├── registration/      注册流程(生成选项、验证响应)
├── authentication/    认证流程(生成选项、验证响应)
├── metadata/          MDS 元数据服务与设置服务
├── helpers/           编解码、COSE 公钥、证书链、签名验证等工具
├── types/             DOM 与内部类型定义
├── package.json       包配置
├── README.md          本文件
├── CHANGELOG.md       更新日志
└── LICENSE            许可
```

* * *

## 安装前准备

### 允许安装脚本执行

本包在安装时可能触发某些依赖包的自动脚本(如 `postinstall` 等);如果你的 npm 全局配置或项目配置禁止了脚本执行(例如设置了 `ignore-scripts=true`),可能会导致安装不完整或运行时异常;

推荐在项目根目录的 `package.json` 中添加 `allowScripts` 字段,显式放行本包及其依赖的脚本:

```json
{
  "allowScripts": {
    "@flun/webauthn-server": true
    // 如果依赖的其它包(如 bcrypt、electron-winstaller 等)也有脚本,请按需添加,格式相同
  }
}
```

> 如果你信任所有安装包,也可以直接在项目 `.npmrc` 中设置 `allow-scripts = false`(表示关闭脚本拦截,所有脚本均允许执行), 或删除 `ignore-scripts` 字段;

* * *

## 安装

### Node.js 22.12.0 及以上版本

```sh
npm install @flun/webauthn-server
```

> **注意**:本库依赖 Node.js 内置的 `crypto`、`fetch` 等模块,请确保运行环境为 Node.js ≥ 22.12.0;

* * *

## 函数方式

### 注册相关

| 方法 | 描述 |
| --- | --- |
| `generateRegistrationOptions(options)` | 生成用于 `navigator.credentials.create()` 的选项参数 |
| `verifyRegistrationResponse(options)` | 验证客户端返回的注册响应,返回验证结果及凭证信息 |

### 认证相关

| 方法 | 描述 |
| --- | --- |
| `generateAuthenticationOptions(options)` | 生成用于 `navigator.credentials.get()` 的选项参数 |
| `verifyAuthenticationResponse(options)` | 验证客户端返回的认证响应,返回验证结果及更新的计数器 |

### 元数据与设置服务

| 导出项 | 描述 |
| --- | --- |
| `MetadataService` | 协调 FIDO 元数据交互的基础服务实例(`BaseMetadataService` 的实例) |
| `SettingsService` | 管理各类 attestation 声明格式根证书的服务实例 |
| `supportedCOSEAlgorithmIdentifiers` | 支持的加密算法标识符数组 |
| `AlgSign` | 支持的签名算法数组 |

### 辅助工具函数(`helpers` 模块)

可通过 `@flun/webauthn-server/helpers` 导入所有底层工具;

#### 编解码与转换

| 函数 | 描述 |
| --- | --- |
| `fromBuffer(buffer)` | 将 ArrayBuffer 编码为 Base64URL 字符串 |
| `toBuffer(base64url)` | 将 Base64URL 字符串解码为 ArrayBuffer |
| `utf8Tob64url(str)` | UTF-8 字符串 → Base64URL |
| `b64urlToUtf8(str)` | Base64URL → UTF-8 字符串 |
| `toBase64(base64url)` | Base64URL → 标准 Base64 |
| `isBase64(str)` | 检查是否为 Base64 编码 |
| `isBase64URL(str)` | 检查是否为 Base64URL 编码 |
| `trimPadding(str)` | 移除 Base64URL 填充字符 |
| `fromHex(hex)` | 十六进制字符串 → Uint8Array |
| `toHex(buf)` | Uint8Array → 十六进制字符串 |
| `utf8Tobytes(str)` | UTF-8 → Uint8Array |
| `bytesToUtf8(buf)` | Uint8Array → UTF-8 |
| `asciiToBytes(str)` | ASCII → Uint8Array |
| `areEqual(a, b)` | 比较两个 Uint8Array 是否相等 |
| `concat(...arrays)` | 拼接多个 Uint8Array |
| `toDataView(buf)` | 转换为 DataView 对象 |

#### COSE 公钥处理

| 类型/函数 | 描述 |
| --- | --- |
| `COSEKEYS`, `COSEKTY`, `COSECRV`, `COSEALG` | COSE 标准键值枚举 |
| `COSEPublicKey`, `COSEPublicKeyOKP`, `COSEPublicKeyEC2`, `COSEPublicKeyRSA` | COSE 公钥类型 |
| `isCOSEPublicKeyOKP()`, `isCOSEPublicKeyEC2()`, `isCOSEPublicKeyRSA()` | 类型守卫 |
| `isCOSEKty()`, `isCOSECrv()`, `isCOSEAlg()` | COSE 参数值检查 |
| `decodeCredentialPublicKey(buf)` | 解码 CBOR 编码的凭证公钥为 Map 对象 |
| `convertCOSEtoPKCS(coseKey)` | 将 COSE 公钥转换为 PKCS 格式 |
| `convertX509PublicKeyToCOSE(certDer)` | 从 X.509 证书提取公钥并转换为 COSE 结构 |

#### 证书处理

| 函数/类 | 描述 |
| --- | --- |
| `convertCertBufferToPEM(buf)` | 将证书缓冲区转换为 PEM 字符串 |
| `convertPEMToBytes(pem)` | 将 PEM 证书转换为字节数组 |
| `getCertificateInfo(pem)` | 提取 PEM 证书的颁发者、主题、有效期等信息 |
| `isCertRevoked(certPem)` | 检查证书是否被其 CRL 吊销 |
| `validateCertificatePath(certs)` | 验证证书链的有效性 |
| `validateExtFIDOGenCEAAGUID(cert, aaguid)` | 校验证书中的 FIDO Gen CE AAGUID 扩展 |
| `InvalidSubjectAndIssuer` | 证书链验证失败时抛出的错误类 |

#### 认证器数据解析

| 函数/类型 | 描述 |
| --- | --- |
| `decodeAttestationObject(buf)` | 解析 attestationObject 缓冲区 |
| `decodeClientDataJSON(base64url)` | 解析 clientDataJSON |
| `parseAuthenticatorData(authData)` | 解析 authData,返回可读结构 |
| `parseBackupFlags(flags)` | 解析备份状态标志 (BE/BS) |
| `decodeAuthenticatorExtensions(buf)` | 解码扩展数据 |
| `InvalidBackupFlags` | 备份标志无效时抛出的错误类 |

#### 签名验证与哈希

| 函数 | 描述 |
| --- | --- |
| `verifySignature({ signature, data, publicKey })` | 通用签名验证入口 |
| `verifyEC2()`, `verifyOKP()`, `verifyRSA()` | 特定算法签名验证 |
| `toHash(data, algorithm?)` | 计算哈希摘要(默认 SHA-256) |
| `mapX509SignatureAlgToCOSEAlg(oid)` | X.509 签名算法 OID → COSE 算法 ID |

#### 通用工具

| 函数/类 | 描述 |
| --- | --- |
| `generateChallenge()` | 生成随机挑战值 |
| `generateUserID()` | 生成随机用户 ID |
| `matchExpectedRPID(rpIdHash, expectedRPIDs)` | 匹配 RP ID 哈希值 |
| `UnexpectedRPIDHash` | RP ID 不匹配时抛出的错误类 |
| `fetch(url, options?)` | 跨运行时的 fetch 封装 |
| `getLogger(name?)` | 获取基于 debug 的日志记录器 |
| `convertAAGUIDToString(aaguid)` | 将 AAGUID 缓冲区转换为 UUID 字符串 |
| `digest(algorithm, data)` | 生成数据摘要 |
| `getRandomValues(arr)` | 填充随机字节 |
| `verify(algorithm, key, signature, data)` | 底层验签函数 |

\*\*\* 当前只是部分,更多请自行查看安装包 \*\*\*

### 集成示例

#### 后端集成示例

以下是一个基于 Express 的完整后端示例,展示了用户注册与登录的 WebAuthn 流程;

```js
import express from 'express';
import {
  generateRegistrationOptions, verifyRegistrationResponse, generateAuthenticationOptions, verifyAuthenticationResponse
} from '@flun/webauthn-server';

const app = express();
app.use(express.json());

// 模拟用户数据库
const users = {
  'user@example.com': {
    id: Buffer.from('user-id-buffer'),
    credentials: []
  }
};

// 临时挑战存储(生产环境建议使用 session 或 redis)
const challengeStore = new Map();

// 1. 注册 - 生成选项
app.post('/api/register/begin', async (req, res) => {
  const { username } = req.body;
  const user = users[username];
  if (!user) return res.status(404).json({ error: 'User not found' });

  const options = await generateRegistrationOptions({
    rpName: 'My App',
    rpID: 'localhost',
    userName: username,
    userID: user.id,
    attestationType: 'none',
  });

  challengeStore.set(username + '_reg', options.challenge);
  res.json(options);
});

// 2. 注册 - 验证响应
app.post('/api/register/complete', async (req, res) => {
  const { username, response } = req.body;
  const expectedChallenge = challengeStore.get(username + '_reg');

  const verification = await verifyRegistrationResponse({
    response,
    expectedChallenge,
    expectedOrigin: 'http://localhost:3000',
    expectedRPID: 'localhost',
    requireUserVerification: true,
  });

  if (verification.verified) {
    const { credential } = verification.registrationInfo;
    users[username].credentials.push({
      id: credential.id,
      publicKey: credential.publicKey,
      counter: credential.counter,
      transports: credential.transports
    });
    challengeStore.delete(username + '_reg');
    res.json({ verified: true });
  } else {
    res.status(400).json({ verified: false });
  }
});

// 3. 认证 - 生成选项
app.post('/api/login/begin', async (req, res) => {
  const { username } = req.body;
  const user = users[username];
  if (!user) return res.status(404).json({ error: 'User not found' });

  const options = await generateAuthenticationOptions({
    rpID: 'localhost',
    allowCredentials: user.credentials.map(cred => ({
      id: cred.id,
      type: 'public-key',
      transports: cred.transports,
    })),
  });

  challengeStore.set(username + '_auth', options.challenge);
  res.json(options);
});

// 4. 认证 - 验证响应
app.post('/api/login/complete', async (req, res) => {
  const { username, response } = req.body;
  const expectedChallenge = challengeStore.get(username + '_auth');
  const user = users[username];
  const credential = user.credentials.find(c => c.id === response.id);

  const verification = await verifyAuthenticationResponse({
    response,
    expectedChallenge,
    expectedOrigin: 'http://localhost:7296',
    expectedRPID: 'localhost',
    credential,
  });

  if (verification.verified) {
    credential.counter = verification.authenticationInfo.newCounter;
    challengeStore.delete(username + '_auth');
    res.json({ verified: true });
  } else {
    res.status(400).json({ verified: false });
  }
});

app.listen(3001, () => console.log('Backend running on port 3001'));
```

#### 前端配合说明

前端需使用配套的浏览器库 `@flun/webauthn-browser`,可通过 CDN 或 npm 引入;

```html
<script src="https://unpkg.com/@flun/webauthn-browser/dist/index.js"></script>
```

调用示例:

```js
// 注册
const regOptions = await fetch('/api/register/begin', ...).then(r => r.json());
const regResponse = await flunWebAuthnBrowser.startRegistration({ optionsJSON: regOptions });
await fetch('/api/register/complete', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username, response: regResponse })
});

// 登录
const authOptions = await fetch('/api/login/begin', ...).then(r => r.json());
const authResponse = await flunWebAuthnBrowser.startAuthentication({ optionsJSON: authOptions });
await fetch('/api/login/complete', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username, response: authResponse })
});
```

* * *

## 常见问题

### 验证失败时会抛出哪些错误?

库中大部分验证方法会在失败时抛出明确的错误类,例如:

-   `UnexpectedRPIDHash`:RP ID 哈希不匹配
-   `InvalidSubjectAndIssuer`:证书链无效
-   `InvalidBackupFlags`:备份标志组合非法

### 如何捕获这些错误?

建议使用 `try...catch` 捕获并作出相应处理;

* * *

## 许可证

ISC © [flun](https://github.com/OpenFlun)

* * *

## 贡献

-   [GitHub 仓库](https://github.com/OpenFlun/webauthn-server)
-   [gitee 仓库](https://gitee.com/openflun/webauthn-server)
-   [npm 包页面](https://www.npmjs.com/package/@flun/webauthn-server)
-   [配套前端库 @flun/webauthn-browser](https://www.npmjs.com/package/@flun/webauthn-browser)

## 常见问题

### @flun/webauthn-server 是什么？

节点\.js → WebAuthn/Passkey →; 19\. TypeScript → CBOR →; 2;

### 如何安装 @flun/webauthn-server？

在项目目录运行 npm install @flun/webauthn-server，或使用 pnpm add / yarn add / bun add。

### @flun/webauthn-server 支持 TypeScript 吗？

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

### @flun/webauthn-server 支持 ESM 还是 CommonJS？

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

### @flun/webauthn-server 需要什么版本的 Node\.js？

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

### @flun/webauthn-server 可以商用吗？

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

### @flun/webauthn-server 的下载量有多少？

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

### @flun/webauthn-server 还在维护吗？

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

