lewis-wow/virtual-webauthn-authenticator
GitHub: lewis-wow/virtual-webauthn-authenticator
一个基于 Node.js 的服务端虚拟 WebAuthn 认证器，通过浏览器扩展拦截 WebAuthn 调用并将其路由到云端认证服务，作为物理安全密钥的替代研究方案。
Stars: 5 | Forks: 0
# 虚拟 WebAuthn 认证器
[](https://codecov.io/gh/lewis-wow/virtual-webauthn-authenticator)
传统的密码身份验证本质上容易受到网络钓鱼和数据泄露的攻击。尽管业界正在向更安全的硬件和平台 passkeys 迈进，但这些解决方案带来了可用性挑战。用户必须管理物理设备，并且如果丢失设备，将面临账号被锁定的风险。服务器端认证器提供了一个更加用户友好的替代方案。它们消除了对特定硬件的严格依赖，但要求在云环境中对密码学材料进行强有力的保护。本论文提出并演示了在 Node.js 中实现此类虚拟认证器的方案。该解决方案包括一个用于拦截标准 WebAuthn API 调用并将其路由到认证器 Web 服务的浏览器扩展。
## 目录
- [虚拟 WebAuthn 认证器](#virtual-webauthn-authenticator)
- [目录](#table-of-contents)
- [关于本项目](#about-this-project)
- [开发前置条件](#development-prerequisites)
- [项目结构](#project-structure)
- [快速开始](#getting-started)
- [1. 安装依赖](#1-install-dependencies)
- [2. 启动基础设施](#2-start-infrastructure)
- [3. 构建包和应用程序](#3-build-packages-and-applications)
- [4. 迁移数据库](#4-migrate-database)
- [5. 在开发模式下运行](#5-run-in-development-mode)
- [运行测试](#run-tests)
- [代码质量](#code-quality)
- [认证器流程](#authenticator-flow)
- [架构](#architecture)
- [示例依赖方应用程序](#example-relying-party-application)
- [1. 设置数据库 Schema](#1-set-up-the-database-schema)
- [2. 在开发模式下运行](#2-run-in-development-mode)
- [配置](#configuration)
- [资源](#resources)
## 关于本项目
这是一个探索服务器端 WebAuthn 认证器作为传统硬件安全密钥替代方案的论文项目。它专为研究和演示目的而设计，不适用于生产环境。
**许可证**：请参阅 [LICENSE](LICENSE) 文件。
## 开发前置条件
- **Node.js** 18+
- 用于 monorepo 的 **pnpm** 包管理器
- 用于 PostgreSQL 和 Key Vault 的 **Docker & Docker Compose**
## 项目结构
- **[`apps/`](./apps/)** — 主应用程序
- **[`packages/`](./packages/)** — 共享库（认证、加密、数据库、UI 组件等）
- **[`examples/`](./examples/)** — 集成了 passkeys 的示例 Next.js 应用程序
## 快速开始
### 1. 安装依赖
```
pnpm install
```
### 2. 启动基础设施
启动 PostgreSQL 和 [LowKey Vault](https://github.com/nagyesta/lowkey-vault) 开发版 Key Vault 模拟器：
```
./docker-compose-test.sh
```
### 3. 构建包和应用程序
```
pnpm build
```
### 4. 迁移数据库
```
pnpm --filter '@repo/prisma' db:migrate
```
### 5. 在开发模式下运行
```
pnpm dev --filter '!@repo/nextjs-example'
```
```
pnpm dev --filter '!@repo/nextjs-example' --filter '!@repo/wxt'
```
有关包含截图的分步指南，请参阅 [docs/how-to-start.md](docs/how-to-start.md)。
### 运行测试
```
pnpm test # All tests
pnpm test:unit # Unit tests
pnpm test:integration # Integration tests
pnpm coverage # Coverage report
```
### 代码质量
你可以使用以下命令来确保代码质量：
```
pnpm format # Format code with Prettier
pnpm lint # Run ESLint
pnpm check-types # Run TypeScript type-checking
```
## 认证器流程
```
+---------------------------------------------------------------+
| RELYING PARTY (Web Server) |
+-------------+-------------------------------------------------+
|
| 0. INITIATION (Challenge / Options)
v
+-------------+-------------------------------------------------+
| BROWSER (Web Extension) |
+-------------+-------------------------------------------------+
| | |
| 1. INTERCEPTION (Main World) |
| [ navigator.credentials proxy ] <--- Web App Call |
| | |
| v window.postMessage |
| | |
| 2. USER INTERFACE (Content Script) |
| [ Confirmation DOM and UI ] |
| | |
| v chrome.runtime.sendMessage |
| | |
| 3. NETWORK LAYER (Background Service Worker) |
| [ Fetch API Wrapper ] |
| | |
+-------------+-------------------------------------------------+
|
v HTTPS
|
+-------------+-------------------------------------------------+
| VIRTUAL AUTHENTICATOR HOST (Server) |
+-------------+-------------------------------------------------+
| | |
| 4. GATEWAY |
| [ API Endpoint ] |
| | |
| v |
| | |
| 5. LOGIC CORE |
| [ Virtual Authenticator Agent ] |
| (Validation / CBOR / Parameters / Extensions) |
| | |
| v |
| | |
| 6. STORAGE & CRYPTO |
| [ Virtual Authenticator ] |
| (Key Vault / Signing / Counters / Attestation / Extensions) |
| |
+---------------------------------------------------------------+
```
## 架构
```
+------------------------------------------------------------+
| |
| PostgreSQL (Database) |
| |
+-----------+--------------------------------------+---------+
| |
| |
| |
+----------+---------+ +----------+---------+ +--------------------+
| | | | | |
| Auth service | | API +-------+ Azure Key Vault |
| | | | | |
+----------+-----+---+ +---+------+---------+ +--------------------+
| | | |
| | | |
| | | |
| | | |
Session| --------------------------+-| | JWT
| +-------------------------| | |
| | | |
| | JWT API key| |
| | | |
+----------+-----+---+ +-----+----+---------+ +--------------------+
| | | | | |
| Console BFF | | Public API BFF +-------+ OpenAPI Docs |
| | | | | |
+----------+---------+ +----------+---------+ +--------------------+
| |
| |
Session| |API key
| |
| |
+----------+---------+ +----------+---------+
| | | |
| Console Frontend | | Browser Extension |
| | | |
+--------------------+ +--------------------+
```
## 示例依赖方应用程序
[`examples/nextjs`](./examples/nextjs/) 目录包含了一个完整的 Next.js 应用程序，它演示了如何使用 [better-auth](https://www.better-auth.com/) 作为依赖方来集成 passkeys。
### 1. 设置数据库 Schema
在 monorepo 根目录下，生成 Prisma client 并推送 schema：
```
pnpm --filter @repo/nextjs-example db:generate && pnpm --filter @repo/nextjs-example db:push
```
### 2. 在开发模式下运行
```
pnpm dev --filter @repo/nextjs-example
```
可通过 `http://localhost:4000` 访问。
## 配置
**环境变量**：使用 [dotenvx](https://dotenvx.com/) 管理开发/测试/生产环境，并提供对机密信息的加密支持。
默认情况下，环境设置为 `development`。可以通过设置 `ENVIRONMENT` 变量来更改此配置（例如，`export ENVIRONMENT=production`）。默认设置定义在 [`.vscode/settings.json`](./.vscode/settings.json) 中。
- 开发/测试：[`.env.development`](./.env.development)，[`.env.test`](./.env.test)（明文）
- 生产环境：[`.env.production`](./.env.production)（已加密），解密密钥在 [`.env.keys`](./.env.keys) 中
- ⚠️ **切勿将 [`.env.keys`](./.env.keys) 提交到版本控制中**
**Key Vault**：使用 [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/)（生产环境）或 [LowKey Vault](https://github.com/nagyesta/lowkey-vault)（开发环境）
## 资源
**规范：**
- [WebAuthn Level 3](https://www.w3.org/TR/webauthn-3/)
- [FIDO CTAP2](https://fidoalliance.org/specs/fido-v2.2-ps-20250714/fido-client-to-authenticator-protocol-v2.2-ps-20250714.html)
**Key Vault：**
- [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/)（生产环境）
- [LowKey Vault](https://github.com/nagyesta/lowkey-vault)（开发环境）
**工具与参考：**
- [WebAuthn.io 演示](https://webauthn.io/)
- [图标：Simple Icons](https://simpleicons.org) | [Lucide](https://lucide.dev/icons/blocks) | [Azure Portal](https://portal.azure.com) | [Plasmo](https://www.plasmo.com)
标签：FIDO2, GNU通用公共许可证, MITM代理, Node.js, WebAuthn, 云密钥, 云端密钥管理, 加密技术, 抗钓鱼认证, 无密码认证, 服务器端认证器, 毕业设计, 测试用例, 浏览器扩展, 消除硬件依赖, 网络安全, 自动化攻击, 虚拟认证器, 请求拦截, 隐私保护