PinMe Worker 集成用户认证时：用…

在 PinMe 项目（Worker TypeScript）中接入邮箱密码或 Google 用户认证，需要创建用户、校验 id_token、查询单个用户或分页列出用户时使用。

适用场景

解决思路

1. 在 backend/src/worker.ts 的 Env 接口中配置 DB: D1Database、API_KEY: string（项目 API Key，用于所有 auth 接口认证）、PROJECT_NAME: string（项目名，所有 auth 接口必须同时传递）、BASE_URL?: string（可选，默认 https://pinme.cloud）。
2. 所有 auth 接口调用时，请求头传 X-API-Key，Query 参数传 project_name，二者必须对应同一个项目；服务端会先校验匹配，再从项目配置取 tenant_id 并转调 Identity Platform。
3. 处理通用认证错误：缺少 X-API-Key 返回 401 和 data.error: X-API-Key header is required；缺少 project_name 返回 400 和 project_name is required；API Key 和项目不匹配返回 401 和 Invalid API key or project name；项目未配置认证租户返回 400 和 Auth service not configured for this project。
4. 定义通用 TypeScript 类型：ApiEnvelope<T> 含 code（200=成功，其他=失败）、msg（ok | fail | invalid param）、data；ApiErrorData 含 error?；UserInfo 含 uid、email、display_name、photo_url?、disabled、email_verified。
5. 创建用户：调用 POST {BASE_URL}/api/v1/auth/create_user?project_name={project_name}，请求头带 X-API-Key 和 Content-Type: application/json，请求体传 email、password 必填，display_name 可选；仅用于邮箱密码注册，成功时用户已创建且验证邮件已发出，失败时自动回滚，不会留下僵尸账号。
6. 创建用户后注意：用户默认仍是未验证状态，需点击邮件验证链接后，verify_token 才能通过校验。
7. 创建用户错误处理：缺少 email/password 返回 400 和 email and password are required；上游创建失败返回 502 和 Failed to create user；发送验证邮件失败返回 500 和 Failed to send verification email. Please try again.。
8. 实现 createAuthUser：用 env.BASE_URL ?? 'https://pinme.cloud' 作为 baseUrl，对 project_name 做 encodeURIComponent，POST 后解析 ApiEnvelope<UserInfo | ApiErrorData>；若 !resp.ok 或 result.code !== 200，返回 data.error 或 result.msg；否则返回 user。
9. 校验 id_token：调用 POST {BASE_URL}/api/v1/auth/verify_token?project_name={project_name}，请求头带 X-API-Key 和 Content-Type: application/json，请求体传 { id_token }；适用于校验前端登录后拿到的 id_token（邮箱密码或 Google 登录均适用）。
10. 校验 id_token 注意：token 合法但邮箱未验证时返回 403，不是 401。
11. 校验 id_token 成功响应 data 类型为 VerifyTokenData：含 uid、email?、tenant_id、claims: Record<string, unknown>。
12. 校验 id_token 错误处理：缺少 id_token 返回 400 和 id_token is required；token 无效或过期返回 401 和 Invalid or expired token；邮箱未验证返回 403 和 Email not verified. Please check your inbox and verify your email address.。
13. 实现 verifyAuthToken：POST 后解析 ApiEnvelope<VerifyTokenData | ApiErrorData>；若失败，error 取 data.error 或 result.msg，emailNotVerified 设为 resp.status === 403；成功返回 uid 和 email。
14. 查询单个用户：调用 GET {BASE_URL}/api/v1/auth/user?project_name={project_name}&uid={uid}，请求头带 X-API-Key。
15. 查询单个用户错误处理：缺少 uid 返回 400 和 uid is required；用户不存在返回 404 和 User not found；上游查询失败返回 502 和 Failed to get user。
16. 实现 getAuthUser：GET 后解析 ApiEnvelope<UserInfo | ApiErrorData>；若 !resp.ok 或 result.code !== 200，返回 data.error 或 result.msg；否则返回 user。
17. 列出用户：调用 GET {BASE_URL}/api/v1/auth/list_users?project_name={project_name}，请求头带 X-API-Key；默认 max_results=100，最大 1000，通过 next_page_token 循环翻页。
18. 列出用户 Query 参数：project_name 必填；page_token 可选，用作分页游标；max_results 可选，每页数量 1–1000。
19. 实现 listAuthUsers：用 new URL('/api/v1/auth/list_users', baseUrl)，searchParams 设置 project_name，若 options.pageToken 设置 page_token，若 options.maxResults 设置 max_results；GET 后解析 ApiEnvelope<{ users: UserInfo[]; next_page_token?: string } | ApiErrorData>；若失败返回 error；成功返回 users 和 nextPageToken。
20. 批量遍历所有用户：实现 iterAllUsers，do 循环调用 listAuthUsers(env, { pageToken, maxResults: 1000 })，若有 error 则 throw new Error(error)，逐个 yield user，pageToken = nextPageToken，直到 pageToken 为空。
21. 前端集成 Firebase Auth：create_worker 响应中包含 public_client_config，前端用它初始化 Firebase Auth SDK；pinme create 会自动将 public_client_config 写入 frontend/src/utils/config.ts，无需手动创建该文件。
22. 区分两种 api_key：data.api_key 是项目 API Key，用于调用本文所有代理接口，不能暴露到浏览器，只给 Worker/服务端；data.public_client_config.auth_api_key 是 Firebase Web API Key，用于初始化前端登录 SDK，可以暴露。
23. public_client_config 字段使用：auth_api_key 用于 initializeApp({ apiKey })；auth_domain 用于 initializeApp({ authDomain })；auth_project_id 用于 initializeApp({ projectId })；tenant_id 必须设置 auth.tenantId = config.tenant_id，否则 token 归属错误。
24. 前端 TypeScript 实现：createProjectAuth 用 initializeApp 和 getAuth 创建 Auth，并设置 auth.tenantId；loginWithEmail 用 signInWithEmailAndPassword，返回 credential.user.getIdToken()；loginWithGoogle 用 signInWithPopup(new GoogleAuthProvider())，返回 credential.user.getIdToken()。
25. 前端职责边界：前端只负责登录和拿 id_token，不要直接持有项目 api_key；verify_token 必须由 Worker/服务端代调。
26. 邮箱密码注册典型调用链路：create_user 创建用户并发出验证邮件 → 用户点击邮件链接完成验证 → 前端登录拿到 id_token → verify_token 校验 token 并取得 uid → 需要时再调 getAuthUser 读取完整用户信息。
27. Google 登录典型调用链路：前端完成 Google Sign-In 并拿到 id_token → verify_token 校验 token，无需调用 create_user。
28. 易错点：只传 X-API-Key 忘记 project_name 时，每个请求都要同时带 X-API-Key header 和 project_name query。
29. 易错点：verify_token 返回 403 时不要当 token 失效处理，403 = 邮箱未验证，提示用户检查邮箱；401 才是 token 失效。
30. 易错点：create_user 成功不代表邮箱已验证，创建成功只代表验证邮件已发，用户必须点击后才算验证。
31. 易错点：list_users 不要只取第一页，有 next_page_token 时需继续请求，直到为空。
32. 易错点：成功判断不要只看 resp.ok，要同时判断 resp.ok && result.code === 200。

适用边界 · 注意事项

• 不适用于非 PinMe 项目或未使用 PinMe Identity Platform auth proxy API 的认证集成。
• 不适用于项目未配置认证租户的场景，此时调用会返回 Auth service not configured for this project。
• 不适用于希望在前端直接持有项目 API Key 或由前端直接调用 verify_token 的场景。