演示说明： 登录端点受自适应 PoW 挑战保护——重复失败会返回更高的工作量证明难度。基于缓存的速度限制已实现并测试，但当前未在在线演示中启用；翻转 app.ts 中的 createCacheClient（位于 apps/cloudflare-workers/src/app.ts）可激活它。

一个从零开始为 Cloudflare Workers 构建的认证参考实现——PBKDF2 密码哈希、JWT 双令牌会话、常量时间比较、滑动过期和可移除的可观测性插件——全部通过 Hono、Turso（可选 Valkey/Redis 缓存）和严格的 TypeScript 集成。

每个设计选择都追溯到一个标准：NIST SP 800-63B 用于凭证，NIST SP 800-132 用于密钥派生，OWASP ASVS 用于验证，以及 RFC 8725 用于 JWT 最佳实践。

正在发布产品？ 请改用 Better Auth——它自带 OAuth、通行密钥、多因素认证、速率限制等功能，并拥有活跃的插件生态。此仓库旨在教你认证如何工作，而非替代生产级库。

为何创建此仓库

• 阅读代码，而不仅仅是文档——每个安全属性（时间恒定拒绝、会话关联撤销、算法固定）都已实现并测试，而不仅仅是描述
• 贯穿始终的 NIST + OWASP + RFC 参考——理解每个决策背后的原因
• 超过 630 个测试，包括攻击向量套件（令牌篡改、算法混淆、Unicode 边界情况）
• 可观测性插件——结构化审计日志、自适应 PoW 挑战、代理认证的操作 API 和 WebSocket 事件流——通过 Hono 中间件接入，无需修改核心认证
• 为边缘而生——在 Cloudflare Workers 上运行，使用 Web Crypto API，无 Node.js 依赖
• Apache-2.0——可自由复刻、教学、学习

内含内容

生产环境下一步

本项目有意省略了超出其教学范围的功能。如果你正在将此代码扩展为生产用途（或评估生产认证系统所需），下表按优先级整理了缺口。

对于大多数实际项目，请使用 Better Auth 而非自行构建。

关键——在提供真实用户之前添加

高优先级——生产可靠性

中等优先级——随产品扩展

高级——企业 / 高安全

所有这些都是选择 Better Auth 的绝佳理由。

仓库结构

.
├── apps/
│   └── cloudflare-workers/    # 示例 Worker + Hono 路由
├── packages/
│   ├── core/                  # 认证服务、中间件、加密工具
│   ├── infrastructure/        # 数据库客户端 + 工具
│   ├── observability/         # 事件发射、自适应挑战、操作 API（可移除插件）
│   ├── schemas/               # Zod schemas
│   └── types/                 # 共享 TypeScript 类型
├── tools/
│   └── cli/                   # plctl — 用于 /ops 接口的 Go TUI
└── docs/
    ├── adr/                   # 架构决策记录
    └── audits/                # 安全审计

快速开始

git clone https://github.com/vhscom/private-landing.git
cd private-landing
bun install
bun run dev

就是这样——无需账户、无需 API 密钥、无需 .env 文件。开发服务器以本地 SQLite 数据库和生成的密钥启动。打开 http://localhost:8788 注册账户并探索认证流程。

有 Turso 账户？ 在 apps/cloudflare-workers/ 中放置一个 .dev.vars 文件（参见 .dev.vars.example），然后 bun run dev 将自动使用 wrangler 连接你的远程数据库。使用 bun run dev:local 可强制使用本地服务器。

参见 CONTRIBUTING.md 获取测试和部署说明。

与 AI 一起使用

此仓库包含一个 CLAUDE.md 文件，为 AI 助手提供上下文。使用 Claude Code、Cursor 或类似 AI 驱动的开发工具时：

1. AI 将自动读取 CLAUDE.md 以获取项目上下文
2. docs/adr/ 中的架构决策记录解释了设计选择
3. docs/audits/ 中的安全审计记录了安全态势
4. 测试展示了预期行为和边界情况

代码库设计为 AI 可读，具有清晰的模块边界、全面的类型和描述性命名。

许可证

Apache-2.0