Home

Passkey‐Auth Wiki

Passkey-Auth 是一个以用户体验为先的现代 passkey OAuth / SSO 认证服务。它使用 Flask、SQLite 和 py_webauthn 实现 WebAuthn passkey 注册、登录、OAuth authorization code flow、link challenge flow 和服务端 session 校验。

这个项目适合两类读者：

• 大众开发者：想快速理解如何把 passkey 登录接入自己的 Web 应用。
• Agents / Vibe Coding：想让 AI coding agent 基于清晰项目地图、安全约束和修改入口继续扩展。

你可以用它做什么

能力	用途
Passkey 注册	为用户创建 WebAuthn credential
用户名登录	用户输入账号后只允许对应 passkey 登录
无用户名登录	浏览器弹出可用 passkey，用户直接选择
OAuth authorization code flow	标准第三方站点接入，后端用 code 换 token
Link challenge flow	类 Cloudflare 的跳转验证，成功后回跳签名参数
Server session verify API	后端服务用 Bearer token 校验 Auth session
注册入口保护	默认关闭注册，避免公开环境被批量创建账号
现代 UI	极简品牌入口、响应式布局、暗色模式、细腻状态反馈
Agent-friendly codebase	配置集中、测试覆盖、模块边界清楚

快速入口

• Quick Start
• Feature Guide
• OAuth and SSO Integration
• Configuration and Deployment
• Security Model
• Agents Vibe Coding Guide
• Troubleshooting

推荐理解顺序

1. 先读 Quick Start，本地跑起来。
2. 再读 Feature Guide，了解所有用户可见能力。
3. 要接入业务系统，读 OAuth and SSO Integration。
4. 要部署生产环境，读 Configuration and Deployment 和 Security Model。
5. 要让 AI agent 继续开发，读 Agents Vibe Coding Guide。

项目精神

这个项目不是只展示“能登录”，而是展示一种更舒服的 passkey 登录体验：

• 首屏不是表单堆叠，而是安静、品牌化、低干扰的 Auth WebUI。
• 浏览器 passkey 是主要交互，页面只提供必要状态。
• OAuth callback 不泄露用户名，只传递必要的 code/state 或 challenge result。
• 后端始终负责最终身份判断，不把浏览器 URL 里的 success=true 当作可信登录依据。