Align credential storage with the implemented threat model

The Rust app currently writes provider credentials to a local plaintext JSON file, while repository guidance and file headers still described a Keychain-backed vault. This records the product choice explicitly, documents the local-file security boundary, adds a settings-page notice, and limits raw credential read/write IPC to the main window instead of exposing it to auxiliary windows by default.

Constraint: Issue #230 asks to resolve the mismatch without leaving docs, implementation, and threat model contradictory.

Rejected: Reintroduce platform Keychain storage | larger cross-platform migration and dependency change outside the minimal fix.

Confidence: high

Scope-risk: narrow

Directive: Do not describe credentials as Keychain-backed unless the persistence implementation actually changes to a platform credential vault.

Tested: npm run -s build; cargo check --manifest-path src-tauri/Cargo.toml; git diff --check; grep for stale Keychain-first wording.

Not-tested: Manual Settings window credential editing in a packaged Tauri app.

Related: #230

Author: H-Chris233

AGENTS.md

@@ -64,7 +64,7 @@ recorder.rs                                   Mic → 16 kHz mono Int16 PCM, RMS
 asr/{mod,frame,volcengine,whisper}.rs         ASR providers: Volcengine streaming WebSocket + Whisper HTTP
 polish.rs                                     OpenAI-compatible chat completions (Ark / DeepSeek / etc.)
 insertion.rs                                  AX focused-element write → clipboard + Cmd+V → copy-only fallback
-persistence.rs                                History/preferences/vocab JSON + Keychain credentials
+persistence.rs                                History/preferences/vocab JSON + local credentials JSON
 coordinator.rs + commands.rs + lib.rs         State machine, IPC surface, tray icon, window plumbing
 permissions.rs                                TCC checks (Accessibility / Microphone)
 
@@ -91,9 +91,9 @@ Invariants:
 
 ### Permissions, credentials, on-disk state
 
-- **Bundle ID `com.openless.app`** is hard-coded in `openless-all/app/src-tauri/tauri.conf.json` and `CredentialsVault.serviceName`. Changing it breaks Keychain lookups *and* every existing TCC grant.
+- **Bundle ID `com.openless.app`** is hard-coded in `openless-all/app/src-tauri/tauri.conf.json`. Changing it breaks existing TCC grants.
 - **TCC**: Microphone + Accessibility + AppleEvents. `NSMicrophoneUsageDescription` / `NSAccessibilityUsageDescription` / `NSAppleEventsUsageDescription` live in `openless-all/app/src-tauri/Info.plist`. After a fresh build that resets TCC, the app must be **fully quit and relaunched** after granting Accessibility before the global hotkey tap installs.
-- **Credentials** live in Keychain under accounts in `CredentialAccount` (`volcengine.app_key`, `volcengine.access_key`, `volcengine.resource_id`, `ark.api_key`, `ark.model_id`, `ark.endpoint`). The plaintext fallback at `~/.openless/credentials.json` is read on first launch so legacy users keep their creds without re-entering. Never hard-code keys.
+- **Credentials** live in a local plaintext JSON file, not Keychain / Credential Manager / Secret Service. macOS / Linux use `~/.openless/credentials.json`; Windows uses `%APPDATA%\OpenLess\credentials.json`. Unix builds set the directory to `0700` and the file to `0600`, which reduces cross-user exposure but does not protect against same-user processes, backups, sync tools, or diagnostics. Never hard-code keys or include this file in logs, exports, build artifacts, or bug reports.
 - **Per-user data**:
   - macOS: `~/Library/Application Support/OpenLess/{history.json, preferences.json, dictionary.json}` — capped at 200 history entries. **Do not rename `dictionary.json` to `vocab.json`** (drops user data).
   - Windows: `%APPDATA%\OpenLess\`

CLAUDE.md

@@ -64,7 +64,7 @@ recorder.rs                                   Mic → 16 kHz mono Int16 PCM, RMS
 asr/{mod,frame,volcengine,whisper}.rs         ASR providers: Volcengine streaming WebSocket + Whisper HTTP
 polish.rs                                     OpenAI-compatible chat completions (Ark / DeepSeek / etc.)
 insertion.rs                                  AX focused-element write → clipboard + Cmd+V → copy-only fallback
-persistence.rs                                History/preferences/vocab JSON + Keychain credentials
+persistence.rs                                History/preferences/vocab JSON + local credentials JSON
 coordinator.rs + commands.rs + lib.rs         State machine, IPC surface, tray icon, window plumbing
 permissions.rs                                TCC checks (Accessibility / Microphone)
 
@@ -91,9 +91,9 @@ Invariants:
 
 ### Permissions, credentials, on-disk state
 
-- **Bundle ID `com.openless.app`** is hard-coded in `openless-all/app/src-tauri/tauri.conf.json` and `CredentialsVault.serviceName`. Changing it breaks Keychain lookups *and* every existing TCC grant.
+- **Bundle ID `com.openless.app`** is hard-coded in `openless-all/app/src-tauri/tauri.conf.json`. Changing it breaks existing TCC grants.
 - **TCC**: Microphone + Accessibility + AppleEvents. `NSMicrophoneUsageDescription` / `NSAccessibilityUsageDescription` / `NSAppleEventsUsageDescription` live in `openless-all/app/src-tauri/Info.plist`. After a fresh build that resets TCC, the app must be **fully quit and relaunched** after granting Accessibility before the global hotkey tap installs.
-- **Credentials** live in Keychain under accounts in `CredentialAccount` (`volcengine.app_key`, `volcengine.access_key`, `volcengine.resource_id`, `ark.api_key`, `ark.model_id`, `ark.endpoint`). The plaintext fallback at `~/.openless/credentials.json` is read on first launch so legacy users keep their creds without re-entering. Never hard-code keys.
+- **Credentials** live in a local plaintext JSON file, not Keychain / Credential Manager / Secret Service. macOS / Linux use `~/.openless/credentials.json`; Windows uses `%APPDATA%\OpenLess\credentials.json`. Unix builds set the directory to `0700` and the file to `0600`, which reduces cross-user exposure but does not protect against same-user processes, backups, sync tools, or diagnostics. Never hard-code keys or include this file in logs, exports, build artifacts, or bug reports.
 - **Per-user data**:
   - macOS: `~/Library/Application Support/OpenLess/{history.json, preferences.json, dictionary.json}` — capped at 200 history entries. **Do not rename `dictionary.json` to `vocab.json`** (drops user data).
   - Windows: `%APPDATA%\OpenLess\`

README.md

@@ -195,9 +195,14 @@ Logs: `~/Library/Logs/OpenLess/openless.log` (macOS) / `%LOCALAPPDATA%\OpenLess\
 
 ## Credentials
 
-Credentials live in the local Keychain (service = `com.openless.app`). A plaintext JSON file at `~/.openless/credentials.json` (mode 0600, dir 0700) is kept as a dev-mode fallback when Keychain is unavailable.
+OpenLess stores provider credentials in a local plaintext JSON file, not in Keychain / Credential Manager / Secret Service:
 
-The repository contains no API keys, tokens, or private endpoints.
+```text
+macOS / Linux: ~/.openless/credentials.json   # file 0600, parent dir 0700 on Unix
+Windows:       %APPDATA%\OpenLess\credentials.json
+```
+
+Those permissions reduce cross-user reads, but same-user processes, backups, sync tools, and diagnostics can still access the file. Do not include it in logs, exports, build artifacts, or bug reports. The repository contains no API keys, tokens, or private endpoints.
 
 You'll need:
 
@@ -247,7 +252,7 @@ recorder.rs      Mic → 16 kHz mono Int16 PCM, RMS callback
 asr/             Volcengine streaming ASR (WebSocket) + Whisper HTTP
 polish.rs        OpenAI-compatible chat-completions (Ark / DeepSeek / etc.)
 insertion.rs     AX focused-element → clipboard + Cmd+V → copy-only fallback
-persistence.rs   History / preferences / vocab JSON + Keychain credentials
+persistence.rs   History / preferences / vocab JSON + local credentials JSON
 permissions.rs   TCC checks (Accessibility / Microphone)
 coordinator.rs   State machine: Idle → Starting → Listening → Processing
 commands.rs      Tauri IPC surface

README.zh.md

@@ -198,13 +198,14 @@ npm run build
 
 ## 凭据
 
-凭据保存在本机 Keychain（service = `com.openless.app`）。开发期同时维护一份明文 JSON 兜底，用于在 Keychain 不可用时回退：
+OpenLess 将供应商凭据保存为本地明文 JSON 文件，不使用 Keychain / Credential Manager / Secret Service：
 
 ```text
-~/.openless/credentials.json   # 0600，目录 0700
+macOS / Linux: ~/.openless/credentials.json   # Unix 下文件 0600，父目录 0700
+Windows:       %APPDATA%\OpenLess\credentials.json
 ```
 
-仓库本身不包含任何 API Key、Token 或 Endpoint 之外的私有信息。
+这些权限可以降低跨用户读取风险，但同一系统用户下的进程、备份、同步工具或诊断收集仍可能接触该文件。不要把它放进日志、导出包、构建产物或问题反馈。仓库本身不包含任何 API Key、Token 或 Endpoint 之外的私有信息。
 
 需要配置的字段：
 
@@ -254,7 +255,7 @@ recorder.rs      麦克风 → 16 kHz 单声道 Int16 PCM，RMS 回调
 asr/             火山引擎流式 ASR（WebSocket）+ Whisper HTTP
 polish.rs        OpenAI 兼容 chat-completions（Ark / DeepSeek 等）
 insertion.rs     AX focused-element → 剪贴板 + Cmd+V → 仅复制兜底
-persistence.rs   历史记录 / 偏好设置 / 词典 JSON + Keychain 凭据
+persistence.rs   历史记录 / 偏好设置 / 词典 JSON + 本地凭据 JSON
 permissions.rs   TCC 权限检查（辅助功能 / 麦克风）
 coordinator.rs   状态机：Idle → Starting → Listening → Processing
 commands.rs      Tauri IPC 接口

openless-all/app/scripts/windows-real-asr-insertion-smoke.ps1

@@ -597,7 +597,7 @@ if ($RequireJsonCredentials -and (-not $credentialStatus.VolcengineConfigured -o
   throw "Real ASR regression requires configured Volcengine ASR and Ark LLM credentials."
 }
 if (-not $credentialStatus.VolcengineConfigured -or -not $credentialStatus.ArkConfigured) {
-  Write-Warning "Legacy credentials.json is incomplete; continuing because the app may use the OS credential vault."
+  Write-Warning "credentials.json is incomplete; continuing because credentials may be configured during the app session."
 }
 
 $logPath = Join-Path $env:LOCALAPPDATA "OpenLess\Logs\openless.log"

openless-all/app/src-tauri/src/commands.rs

@@ -5,7 +5,7 @@ use std::time::Duration;
 
 use serde::Serialize;
 use serde_json::Value;
-use tauri::{AppHandle, Emitter, State};
+use tauri::{AppHandle, Emitter, State, Window};
 
 use crate::coordinator::Coordinator;
 use crate::permissions::{self, PermissionStatus};
@@ -143,7 +143,8 @@ fn configured(field: &Option<String>) -> bool {
 }
 
 #[tauri::command]
-pub fn set_credential(account: String, value: String) -> Result<(), String> {
+pub fn set_credential(window: Window, account: String, value: String) -> Result<(), String> {
+    ensure_main_window(&window)?;
     let acc = parse_account(&account)?;
     if value.is_empty() {
         CredentialsVault::remove(acc).map_err(|e| e.to_string())
@@ -173,13 +174,22 @@ pub fn set_active_llm_provider(provider: String) -> Result<(), String> {
 }
 
 /// 读出某个账号的实际值（用于设置页预填表单）。
-/// 与 Swift `CredentialsVault.get` 同语义，先 Keychain，缺则回落 ~/.openless/credentials.json。
+/// 凭据以本地 JSON 文件保存；只允许主设置窗口读取 raw secret，避免胶囊 / QA 等辅助窗口默认暴露。
 #[tauri::command]
-pub fn read_credential(account: String) -> Result<Option<String>, String> {
+pub fn read_credential(window: Window, account: String) -> Result<Option<String>, String> {
+    ensure_main_window(&window)?;
     let acc = parse_account(&account)?;
     CredentialsVault::get(acc).map_err(|e| e.to_string())
 }
 
+fn ensure_main_window(window: &Window) -> Result<(), String> {
+    if window.label() == "main" {
+        Ok(())
+    } else {
+        Err("credential access is only allowed from the main window".to_string())
+    }
+}
+
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ProviderCheckResult {

openless-all/app/src-tauri/src/persistence.rs

@@ -1,16 +1,19 @@
 //! Local persistence: history JSON, user preferences JSON, vocab JSON, and
-//! Keychain-backed credentials vault.
+//! plaintext credentials JSON.
 //!
 //! Storage roots:
 //! - macOS:   `~/Library/Application Support/OpenLess`
 //! - Windows: `%APPDATA%\OpenLess`
 //! - Linux:   `$XDG_DATA_HOME/OpenLess` or `~/.local/share/OpenLess`
 //!
-//! Divergence from Swift: the Swift `CredentialsVault` falls back to a JSON
-//! file (`~/.openless/credentials.json`) when Keychain is unavailable. The
-//! Rust port intentionally does NOT replicate that fallback — we rely solely
-//! on the platform keyring. The macOS service name (`com.openless.app`) is
-//! preserved so existing Keychain entries from the Swift app remain readable.
+//! Credential storage policy: the Tauri app stores provider credentials in a
+//! local JSON file, not in Keychain / Credential Manager / Secret Service.
+//! - macOS / Linux: `~/.openless/credentials.json`
+//! - Windows: `%APPDATA%\OpenLess\credentials.json`
+//! Unix builds set the parent directory to 0700 and the file to 0600. This
+//! protects against other OS users, but same-user processes, backups, sync
+//! tools, and diagnostics can still read plaintext secrets. Do not include the
+//! credentials file in exports, logs, or build artifacts.
 
 use std::fs;
 use std::path::{Path, PathBuf};
@@ -32,9 +35,8 @@ const PREFERENCES_FILE: &str = "preferences.json";
 const VOCAB_FILE: &str = "dictionary.json";
 const VOCAB_PRESETS_FILE: &str = "vocab-presets.json";
 
-/// Swift 老 `CredentialsVault` 的 JSON 备用路径。
-/// 升级到 Tauri 版后，先尝试 Keychain；Keychain 没有时回落读这个文件，
-/// 让用户在 Swift 版填过的凭据无需重输。
+/// 当前 Tauri 凭据 JSON 路径使用的目录 / 文件名。
+/// 这是唯一写入位置，不是 Keychain fallback。
 const LEGACY_CREDS_DIR: &str = ".openless";
 const LEGACY_CREDS_FILE: &str = "credentials.json";
 
@@ -117,10 +119,8 @@ fn read_or_default<T: for<'de> Deserialize<'de> + Default>(path: &Path) -> Resul
 
 // ───────────────────────── credentials JSON store ─────────────────────────
 //
-// 与 Swift `Sources/OpenLessPersistence/CredentialsVault.swift` 同源——纯 JSON 文件，
-// 路径 `~/.openless/credentials.json`，权限 0600。**故意不用 Keychain**：
-// ad-hoc 签名每次构建 hash 都变，Keychain ACL 失效后会触发逐账号弹框；用户已明确
-// 选择"直接写本地文件"。
+// 纯 JSON 凭据文件，非平台凭据库。路径见 credentials_path()，Unix 权限为
+// 目录 0700 / 文件 0600。该边界只防跨用户读取，不防同用户进程、备份或诊断收集。
 //
 // v1 schema：
 //   {
@@ -636,9 +636,8 @@ pub enum CredentialAccount {
 }
 
 impl CredentialAccount {
-    /// Account names match the Swift `CredentialAccount` constants exactly so
-    /// existing Keychain entries written by the macOS Swift app remain
-    /// readable after upgrade.
+    /// Stable account keys used inside credentials.json.
+    /// The method name is kept for compatibility with older call sites; it no longer implies Keychain usage.
     pub fn keyring_account(&self) -> &'static str {
         match self {
             CredentialAccount::VolcengineAppKey => "volcengine.app_key",
@@ -686,8 +685,7 @@ pub struct CredentialsSnapshot {
 pub struct CredentialsVault;
 
 impl CredentialsVault {
-    /// 历史保留：Swift 时代以此名作为 Keychain service。Rust 不再使用 Keychain，
-    /// 但暴露此常量给可能仍依赖它的代码点。
+    /// 历史保留的服务名常量；Rust 凭据存储不使用 Keychain。
     pub const SERVICE_NAME: &'static str = "com.openless.app";
 
     pub fn get(account: CredentialAccount) -> Result<Option<String>> {

openless-all/app/src/i18n/en.ts

@@ -291,6 +291,7 @@ export const en: typeof zhCN = {
       llmDesc: 'OpenAI-compatible protocol. Multiple vendors supported.',
       providerLabel: 'Provider',
       llmProviderDesc: 'Selecting a preset auto-fills the default Base URL.',
+      credentialStorageNotice: 'Credentials are stored in a local plaintext JSON file. File permissions reduce cross-user access, but same-user processes and backups may still read it.',
       asrProviderDesc: 'Switching providers automatically loads the matching credentials.',
       asrTitle: 'ASR (transcription)',
       asrDesc: 'Used to turn speech into text in real time.',

openless-all/app/src/i18n/zh-CN.ts

@@ -289,6 +289,7 @@ export const zhCN = {
       llmDesc: 'OpenAI 兼容协议，支持多家供应商切换。',
       providerLabel: '供应商',
       llmProviderDesc: '选择后将自动填入 Base URL 默认值。',
+      credentialStorageNotice: '凭据保存为本地明文 JSON 文件。文件权限会降低跨用户读取风险，但同一系统用户下的进程和备份仍可能读取。',
       asrProviderDesc: '切换后将自动选用对应凭据。',
       asrTitle: 'ASR 语音（转写）',
       asrDesc: '用于将口述实时转写为文本。',

openless-all/app/src/i18n/zh-TW.ts

@@ -291,6 +291,7 @@ export const zhTW: typeof zhCN = {
       llmDesc: 'OpenAI 兼容協議，支持多家供應商切換。',
       providerLabel: '供應商',
       llmProviderDesc: '選擇後將自動填入 Base URL 默認值。',
+      credentialStorageNotice: '憑據儲存為本機明文 JSON 檔案。檔案權限會降低跨使用者讀取風險，但同一系統使用者下的程序和備份仍可能讀取。',
       asrProviderDesc: '切換後將自動選用對應憑據。',
       asrTitle: 'ASR 語音（轉寫）',
       asrDesc: '用於將口述實時轉寫爲文本。',