PinMe Worker Auth API Integration 是一份面向 PinMe Worker（TypeScript）的认证集成指南，说明如何在 Worker 中调用 PinMe 平台 Identity Platform 的认证代理接口。
用途 当 PinMe 项目需要使用用户认证时，可用本技能接入邮箱密码注册、校验登录令牌、查询与列出用户等能力。前端负责登录并获取 id_token，Worker/服务端负责代调校验接口。
环境变量 在 backend/src/worker.ts 中定义 Env：DB 为 D1Database；API_KEY 为项目 API Key，用于所有 auth 接口认证；PROJECT_NAME 为项目名，所有 auth 接口必须同时传递；BASE_URL 可选，默认 https://pinme.cloud。API_KEY 和 PROJECT_NAME 是必填凭证，缺一不可。
认证方式 所有接口通用：请求头携带 X-API-Key，Query 参数携带 project_name，两者必填且必须对应同一个项目。服务端先校验两者匹配同一项目，再从项目配置取出 tenant_id，然后转调 Identity Platform。通用错误包括：缺少 X-API-Key 返回 401（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）。
通用类型 ApiEnvelope<T> 包含 code（200=成功，其他=失败）、msg、data；ApiErrorData 含可选 error；UserInfo 含 uid、email、display_name、photo_url、disabled、email_verified。
主要能力 API 1 创建用户：POST {BASE_URL}/api/v1/auth/create_user?project_name={project_name}，仅用于邮箱密码注册。成功时用户已创建且验证邮件已发出，失败自动回滚。创建成功后用户默认未验证，需点击邮件验证链接后 verify_token 才能通过。请求体含 email（必填）、password（必填）、display_name（可选）。错误含 400 缺少 email/password、502 上游创建失败、500 发送验证邮件失败。 API 2 校验 id_token：POST {BASE_URL}/api/v1/auth/verify_token?project_name={project_name}，校验前端登录后拿到的 id_token（邮箱密码或 Google 登录均适用）。注意 token 合法但邮箱未验证时返回 403 而非 401。成功 data 含 uid、email、tenant_id、claims。错误含 400 缺少 id_token、401 token 无效或过期、403 邮箱未验证。 API 3 查询单个用户：GET {BASE_URL}/api/v1/auth/user?project_name={project_name}&uid={uid}。错误含 400 缺少 uid、404 用户不存在、502 上游查询失败。 API 4 列出用户：GET {BASE_URL}/api/v1/auth/list_users?project_name={project_name}，默认 max_results=100，最大 1000，通过 next_page_token 循环翻页。Query 参数含 project_name（必填）、page_token（可选）、max_results（可选，1–1000）。资料同时给出批量遍历所有用户的迭代器示例。
使用方式 技能为每个接口提供了 TypeScript 示例：createAuthUser、verifyAuthToken、getAuthUser、listAuthUsers 以及 iterAllUsers。前端集成方面，create_worker 响应中包含 public_client_config，前端用它初始化 Firebase Auth SDK。需区分两种 api_key：data.api_key 是项目 API Key，调用所有代理接口，不能暴露到浏览器，只给 Worker/服务端；data.public_client_config.auth_api_key 是 Firebase Web API Key，用于初始化前端登录 SDK，可以暴露。public_client_config 字段用途：auth_api_key 用于 initializeApp({ apiKey })、auth_domain 用于 authDomain、auth_project_id 用于 projectId、tenant_id 需设置 auth.tenantId（必须设置，否则 token 归属错误）。前端示例包含 createProjectAuth、loginWithEmail、loginWithGoogle。frontend/src/utils/config.ts 由 pinme create 自动生成，无需手动创建。
典型调用链路 邮箱密码注册流程：create_user 创建用户并发出验证邮件；用户点击邮件链接完成验证；前端登录拿到 id_token；verify_token 校验 token 取得 uid；需要时再调 getAuthUser 读取完整用户信息。 Google 登录流程：前端完成 Google Sign-In 拿到 id_token；verify_token 校验 token（无需调用 create_user）。
限制与易错点 每个请求都要同时带 X-API-Key header 和 project_name query；verify_token 返回 403 表示邮箱未验证，应提示用户检查邮箱，401 才是 token 失效；create_user 成功只代表验证邮件已发，用户必须点击后才算验证；list_users 只取第一页不够，有 next_page_token 时需继续请求直到为空；成功判断应同时满足 resp.ok 与 result.code === 200。前端只负责登录和拿 id_token，不要直接持有项目 api_key，verify_token 必须由 Worker/服务端代调。