[Feature] 优化内置浏览器通行密钥不可用时的登录降级体验
- Dominant language
- TypeScript
- Stars
- 2.7k
- Forks
- 401
- Avg merge
- 21h 48m
- Merged PRs (30d)
- 776
Description
## 背景
在 Cindy 内置浏览器中登录 Google Workspace 账号时,Google 默认推荐“使用通行密钥登录”。
当前 Cindy 内置浏览器中的通行密钥流程无法完成,页面会一直停留在:
> 正在验证您的身份……
> 请使用您的通行密钥完成登录
点击“试试其他方式”后,电话和身份验证器均可以正常完成登录,密码登录也正常。
因此目前判断,问题不是 Google 账号无法登录,也不是 Workspace 的备用验证方式不可用,而是 Cindy 内置浏览器不具备可用的 macOS 平台通行密钥能力时,没有正确降级。
## 复现步骤
1. 在 Cindy 右侧栏打开内置浏览器。
2. 访问 Google 账号登录页。
3. 输入 Google Workspace 账号。
4. 点击“使用通行密钥登录”。
5. 页面长期停留在“正在验证您的身份”。
6. 点击“试试其他方式”。
7. 选择电话或身份验证器,可以正常完成登录。
8. 如果继续排除所有备用验证方式,Google 最终显示“无法登录,请与网域管理员联系”。
## 实际结果
- 默认通行密钥流程无法完成。
- 页面没有超时、失败或“当前环境不支持通行密钥”的提示。
- 用户需要手动点击“试试其他方式”才能继续登录。
- 电话、身份验证器和密码登录均正常。
- “无法登录”只会在用户继续排除所有备用验证方式后出现,不是主要故障。
## 期望结果
当内置浏览器无法使用平台通行密钥时:
1. 不要让页面无限停留在 Google 的验证等待页面。
2. 给出明确的超时或“不支持当前环境”的提示。
3. 提供“试试其他方式”“使用密码”或“在系统浏览器中打开”等回退路径。
4. 如果可以检测到平台认证器不可用,应在进入通行密钥流程前提示用户。
5. 记录必要的诊断信息,方便区分内置浏览器能力限制和 Google 账号策略问题。
## 初步源码调查
Cindy 内置浏览器使用 Electron ``:
- `apps/desktop/src/renderer/features/right-sidebar/lib/browserWebviewPool.ts`
- 使用持久化 partition:`persist:xdmaker-browser-app`
当前 Electron 版本为:
- Electron `41.2.0`
- Chromium `146.0.7680.179`
源码中没有发现:
- `app.configureWebAuthn()`;
- `PublicKeyCredential` 平台能力检测;
- `isUserVerifyingPlatformAuthenticatorAvailable()` 检测;
- WebAuthn 超时或失败处理;
- 通行密钥相关日志;
- Google 登录场景的 Electron WebAuthn 集成测试。
Electron 41.5 才提供 macOS 平台认证器配置 API。当前运行时可以暴露 WebAuthn API,但平台认证器可用性检测结果为 `false`,与“页面提供通行密钥入口、但认证流程无法完成”的现象一致。
另外,当前 macOS 应用 entitlement 中暂未发现:
```text
com.apple.developer.web-browser.public-key-credential
keychain-access-groups
```
相关文件:
- `apps/desktop/release/build-main.entitlements`
- `apps/desktop/scripts/ci/lib.mjs`
- `apps/desktop/forge.config.ts`
## 建议实现方向
### 短期:优化降级体验
1. 检测当前 WebAuthn 平台认证器是否可用。
2. 对通行密钥流程增加超时检测。
3. 超时后提示用户切换到电话、身份验证器或密码。
4. 提供在系统浏览器中完成登录的回退入口。
5. 在日志中记录:
- WebAuthn API 是否存在;
- 平台认证器是否可用;
- 当前 Electron/Chromium 版本;
- 超时和失败原因。
### 后续:评估是否支持 macOS 通行密钥
如果产品需要在 Cindy 内置浏览器中正式支持 macOS Touch ID/平台通行密钥,需要单独评估:
1. 升级到支持 `app.configureWebAuthn()` 的 Electron 版本。
2. 调用 `app.configureWebAuthn()` 初始化平台认证器。
3. 配置 macOS Keychain access group。
4. 将必要 entitlement 加入开发包和正式签名包。
5. 增加 Electron `` 与 macOS 平台认证器的真实集成测试。
6. 验证 Apple Silicon、Intel/T2 等设备差异。
不建议只通过伪装 Chrome User-Agent 解决问题,应先确认宿主平台认证器是否真实可用。
## 验收标准
- 平台认证器不可用时,不再无限停留在 Google 等待页面。
- 用户可以直接切换到电话、身份验证器或密码登录。
- 日志能够记录能力检测和超时原因。
- 在系统 Chrome 支持通行密钥、而 Cindy 不支持时,能够明确提示是内置浏览器能力限制。
- 后续如果支持正式接入 macOS 通行密钥,应有独立的集成测试和签名 entitlement 校验。
Contributor guide
Research direction
Start with apps/desktop/src/renderer/features/right-sidebar/lib/browserWebviewPool.ts and inspect the persisted webview’s WebAuthn capability handling. Review apps/desktop/release/build-main.entitlements, apps/desktop/scripts/ci/lib.mjs, and apps/desktop/forge.config.ts for platform requirements. Done means unavailable platform authentication no longer leaves the Google flow waiting indefinitely, provides a fallback, and records capability, timeout, and failure diagnostics.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- electron, macos, typescript
- Domain
- authentication, desktop, security
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100