用途：在网站中实现、审查或调试 Google 登录/注册，采用 GIS ID-token 流程。仅需确认用户身份时使用该流程：加载 https://accounts.google.com/gsi/client，获取一个 Google 签名的 JWT 并在服务端校验，无需重定向 URI、客户端密钥或存储 Google token。若需代表用户调用 Gmail/Drive/Calendar 等 Google API，应改用 OAuth 2.0 授权码流程，不要仅为登录使用授权码流程。
主要能力与用法：前端先向服务端获取 nonce（GET /api/auth/google/nonce，服务端带 TTL 存储并绑定预认证 HttpOnly cookie），再调用 google.accounts.id.initialize({ client_id, callback, nonce }) 并 renderButton()；GSI 脚本异步加载，需重试渲染。回调收到 { credential } 后单独 POST 到后端，不得当作会话。后端用官方库校验，如 Python 的 google.oauth2.id_token.verify_oauth2_token(credential, transport, CLIENT_ID) 或 Node 的 google-auth-library verifyIdToken({ idToken, audience })，校验签名、aud、iss、exp，并要求 email_verified == true，同时一次性消费预认证会话中的 nonce 并与 token 的 nonce 声明精确比对。随后查找或创建用户，签发自有会话（HttpOnly + Secure + SameSite=Strict cookie），Google token 只校验一次，不存储、不记录日志。
账号关联：以 sub（存为 google_id）为键，不用 email。已有 google_id 则登录；邮箱匹配但无 google_id 时，默认需对现有本地账号重新认证后才关联；仅当 Google 对该地址具权威性（email_verified 且为 @gmail.com 或 token 带 hd 声明）且现有账号邮箱所有权已证明时才可免重认证自动关联。无匹配则创建用户。
登录 CSRF：表单 POST 流程要求 g_csrf_token 在表单体与 cookie 中同时存在且相等（常量时间比较）；JS fetch 流程要求 Sec-Fetch-Site: same-origin，或在该头缺失时校验精确 Origin 白名单，否则失败关闭。CSRF 判断须在 token 校验之前执行。
配置与限制：GCP 中创建 OAuth 客户端 ID（Web 应用），Authorized JavaScript origins 填所有渲染按钮的来源（含 http://localhost:<port>），GIS 的重定向 URI 留空；仅发布 GOOGLE_CLIENT_ID，客户端密钥不使用。CSP 需允许 https://accounts.google.com。GOOGLE_CLIENT_ID 为空时隐藏按钮并返回未配置。需完成安全清单：官方库验签、aud/exp、email_verified、nonce、防预注册劫持、登录 CSRF、自有会话 cookie、/api/auth/* 限流、会话撤销、登出调用 google.accounts.id.disableAutoSelect()。调试常见问题包括来源未授权、按钮不渲染、时钟偏移、audience 不匹配、FedCM 相关警告等。非 Claude Code 环境不运行 PreToolUse 门禁；无浏览器通道时只能读代码验证；创建 OAuth 客户端需人工完成。