Support OS keyring auth for local LLM credentials

[acoliver]

Problem Statement

OpenCodeReview currently documents and examples LLM credentials primarily through configuration files and environment variables such as OCR_LLM_AUTH_TOKEN. This works well in CI, but it is not ideal for local CLI usage on developer machines.

Environment variables can leak through shell history, child process inheritance, process inspection, crash logs, and CI logs. Plain config files are also risky unless users manage permissions carefully.

Proposed Solution

Add first-class OS keyring support for local credentials.

The CLI could provide commands such as:

ocr auth key save <name> <token>
ocr auth key save <name> --stdin
ocr auth key save <name> --prompt
ocr auth key list
ocr auth key delete <name>

The direct form includes the token value; the stdin/prompt forms are safer because they avoid shell history and process-list exposure. Configuration could reference a named credential instead of storing the secret value. At runtime, auth resolution could use this precedence:

1. Explicit CLI option.
2. Named keyring credential.
3. Existing config value.
4. Environment variable fallback.

Suggested design

• Use a cross-platform keyring library where possible.
• Support macOS Keychain, Windows Credential Manager, and Linux Secret Service.
• Detect unavailable, denied, or locked keyrings with actionable messages.
• Keep environment variables supported for CI.
• Consider an encrypted file fallback for headless Linux if implemented carefully with restrictive permissions and clear warnings.

Reference implementation

LLxprt Code has a similar multi-platform design using @napi-rs/keyring with an encrypted fallback. It stores only a key name in profiles and resolves the secret at runtime.

Useful references at commit a50837636f124130cf2d6973d0641e2f4eae02c2:

• SecureStore adapter/options: https://github.com/vybestack/llxprt-code/blob/a50837636f124130cf2d6973d0641e2f4eae02c2/packages/core/src/storage/secure-store.ts#L56-L75
• Dynamic @napi-rs/keyring loader: https://github.com/vybestack/llxprt-code/blob/a50837636f124130cf2d6973d0641e2f4eae02c2/packages/core/src/storage/secure-store.ts#L156-L218
• Keyring availability probe: https://github.com/vybestack/llxprt-code/blob/a50837636f124130cf2d6973d0641e2f4eae02c2/packages/core/src/storage/secure-store.ts#L347-L399
• Keyring-first get/set with encrypted fallback: https://github.com/vybestack/llxprt-code/blob/a50837636f124130cf2d6973d0641e2f4eae02c2/packages/core/src/storage/secure-store.ts#L404-L500
• /key save command: https://github.com/vybestack/llxprt-code/blob/a50837636f124130cf2d6973d0641e2f4eae02c2/packages/cli/src/ui/commands/keyCommand.ts#L66-L145
• /key load command: https://github.com/vybestack/llxprt-code/blob/a50837636f124130cf2d6973d0641e2f4eae02c2/packages/cli/src/ui/commands/keyCommand.ts#L155-L217
• auth-key-name resolution before environment variables: https://github.com/vybestack/llxprt-code/blob/a50837636f124130cf2d6973d0641e2f4eae02c2/packages/core/src/auth/precedence.ts#L645-L650
• Documentation explaining why keyring is preferred over environment variables: https://github.com/vybestack/llxprt-code/blob/a50837636f124130cf2d6973d0641e2f4eae02c2/docs/cli/authentication.md#L62-L134

Acceptance criteria

• Users can save and reference an LLM auth token by name without putting the raw token in config, shell history, or environment variables.
• Existing environment variable workflows continue to work.
• Missing, denied, or locked keyring errors are clear and actionable.
• Documentation explains local keyring usage and CI secret usage separately.

中文说明

问题陈述

OpenCodeReview 目前主要通过配置文件和环境变量（例如 OCR_LLM_AUTH_TOKEN）来记录和演示 LLM 凭据。这种方式在 CI 环境中很好用，但在开发者本地 CLI 场景中并不理想。

环境变量可能通过 shell 历史记录、子进程继承、进程检查、崩溃日志以及 CI 日志等途径泄露。如果用户没有仔细管理文件权限，明文配置文件同样存在风险。

建议方案

为本地凭据提供一等公民的操作系统 keyring 支持。

CLI 可以提供类似下面的命令：

ocr auth key save <name> <token>
ocr auth key save <name> --stdin
ocr auth key save <name> --prompt
ocr auth key list
ocr auth key delete <name>

直接形式包含 token 值；stdin/prompt 形式更安全，因为可以避免写入 shell 历史记录或暴露在进程列表中。配置中可以引用一个命名凭据，而不是直接保存密钥明文。运行时的认证解析可以采用以下优先级：

1. 显式 CLI 参数。
2. 命名的 keyring 凭据。
3. 现有配置值。
4. 环境变量回退。

设计建议

• 尽量使用跨平台 keyring 库。
• 支持 macOS Keychain、Windows Credential Manager 和 Linux Secret Service。
• 当 keyring 不可用、被拒绝访问或处于锁定状态时，给出可操作的错误提示。
• 继续保留环境变量支持，以适配 CI 场景。
• 对于无桌面环境的 headless Linux，可以考虑加密文件回退，但需要严格的文件权限和清晰的安全提示。

参考实现

LLxprt Code 已经有类似的多平台设计：使用 @napi-rs/keyring，并提供加密文件回退。它在 profile 中只保存密钥名称，在运行时解析实际密钥。

上面的英文部分列出了具体代码和文档链接。

验收标准

• 用户可以按名称保存和引用 LLM auth token，不需要把原始 token 放进配置文件、shell 历史记录或环境变量。
• 现有环境变量工作流继续可用。
• 当 keyring 缺失、拒绝访问或被锁定时，错误信息清晰且可操作。
• 文档分别说明本地 keyring 使用方式和 CI secret 使用方式。