makecindy / makecindy/cindy

[Feature] 优化内置浏览器通行密钥不可用时的登录降级体验

Open
#126 3 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.