Agents Vibe Coding Guide

Agents Vibe Coding Guide

本页专门给 AI coding agents、自动化编码助手和 vibe coding 工作流使用。目标是让 agent 快速理解项目边界，安全扩展功能，而不是凭感觉乱改认证核心。

项目一句话

Passkey-Auth 是一个 Flask + SQLite + WebAuthn 的现代 passkey OAuth/SSO demo，强调用户优先 UI、标准 OAuth code flow、link challenge flow 和服务端安全校验。

Agent 修改前必读

优先保持这些不变量：

• WebAuthn challenge 必须保存在后端 session 中，并在 verify 后清理。
• OAuth code 必须一次性消费。
• Link challenge 必须一次性消费。
• state 必须由发起方生成并在 callback 校验。
• status=success 不可信。
• client_secret 和 server token 不得进入前端。
• PASSKEY_ORIGIN 必须与浏览器 origin 匹配。
• 注册默认关闭。

项目地图

passkey_demo/app.py
  Flask app、路由、OAuth flow、challenge flow、server verify

passkey_demo/config.py
  默认配置和环境变量覆盖

passkey_demo/storage.py
  SQLite schema、用户、credential、code、challenge 存储

passkey_demo/webauthn_service.py
  WebAuthn options 生成和 verify 封装

passkey_demo/register_client.py
  动态下发的注册前端模块

passkey_demo/static/main.js
  首页 Logo 交互、无用户名登录、注册面板解锁

passkey_demo/static/oauth_authorize.js
  OAuth/Challenge Auth WebUI 自动 passkey 验证

passkey_demo/templates/
  首页、OAuth 页面、第三方 demo、link challenge demo

tests/
  配置、注册保护、OAuth、link challenge 测试

推荐工作循环

1. 读相关文件，不要全局重构。
2. 明确要改的是 UI、WebAuthn、OAuth、存储还是配置。
3. 小步修改。
4. 跑测试：

.venv/bin/python -m unittest discover -s tests -v

5. 如果改了前端，启动本地服务并用浏览器验证：

PORT=5003 PASSKEY_ORIGIN=http://localhost:5003 .venv/bin/python -m passkey_demo.app

常见任务入口

修改 OAuth client 配置

位置：

passkey_demo/app.py::_oauth_client
passkey_demo/config.py

建议：

• 多 client 不要继续堆环境变量。
• 新增 oauth_clients 表或配置文件。
• 生产环境存 client_secret_hash，不要明文。

增加 refresh token

建议新增：

oauth_refresh_tokens
- token_hash
- client_id
- user_id
- created_at
- expires_at
- revoked_at

不要复用 access token serializer 当 refresh token 存储。

增加用户管理后台

建议新增独立 blueprint 或模块：

passkey_demo/admin.py
templates/admin_*.html

必须增加管理员认证，不要把注册开关当管理员认证。

换数据库

优先保持 PasskeyStore 方法接口不变：

get_user_by_username
get_user_by_id
get_user_by_handle
save_credential
create_oauth_authorization_code
consume_oauth_authorization_code
create_oauth_challenge_request
complete_oauth_challenge_request
consume_oauth_challenge_request

这样 app 层不用大改。

改 UI

位置：

templates/index.html
templates/oauth_authorize.html
static/styles.css
static/oauth.css
static/main.js
static/oauth_authorize.js

约束：

• 保持 Auth WebUI 极简。
• 不要在 OAuth callback URL 或普通 UI 响应中暴露不必要用户信息。
• 表单、状态和按钮在移动端不能溢出。
• 保持暗色模式。

增加日志

建议记录：

• OAuth authorize start
• OAuth token exchange success/fail
• Challenge create/complete/consume
• Registration attempt
• Login verify success/fail

不要记录：

• raw credential
• client secret
• access token
• challenge result token
• full session cookie

Agent 安全红线

不要做这些：

• 把 PASSKEY_REGISTRATION_ENABLED 默认改成 true。
• 在前端保存 client secret。
• callback 只检查 status=success 就登录。
• 让 authorization code 可重复使用。
• 删除 state 校验。
• 为了方便测试关闭 origin/RP ID 校验。
• 把 SQLite 数据库或 .env 加进 git。
• 在 Wiki 或 README 中写入真实密钥。

推荐测试策略

每个功能至少加一种测试：

功能	测试方向
配置	默认值、环境变量覆盖
注册	默认关闭、开启后可解锁
OAuth	authorize 接受合法 callback、拒绝恶意 callback
Callback	state 错误失败
Token	code 可换 token、重复使用失败
Challenge	创建、完成、callback 成功、重放失败
安全	用户名和 passkey 不匹配时拒绝

Agent Prompt 模板

增加一个新 OAuth client 存储

Inspect passkey_demo/app.py and passkey_demo/storage.py.
Add persistent OAuth client storage without changing current demo behavior.
Keep _oauth_client API shape compatible.
Add tests for multiple redirect URIs and invalid clients.
Run unittest.

增加生产部署文档

Read README.md, docs/oauth-integration.md, and passkey_demo/config.py.
Write a deployment page covering HTTPS, RP ID, origin, secrets, database path, reverse proxy, and public repo safety.
Do not add real secrets.

改 Auth UI

Inspect templates/oauth_authorize.html, static/styles.css, and static/oauth_authorize.js.
Improve UI while keeping automatic passkey invocation and existing data-* attributes.
Verify desktop and mobile layout.
Run tests.

Vibe Coding 建议

这个项目适合“边跑边改”的节奏，但认证代码不要只凭视觉满意就结束。每次 vibe coding 结束前至少做：

.venv/bin/python -m unittest discover -s tests -v
git diff
rg -n -uu "real-domain\\.example|github-token-prefix|openai-key-prefix|private-key-marker|\\.env" .

最后确认：

• UI 体验变好了
• 安全不变量没破
• 测试覆盖新增路径
• 文档同步更新