Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

fix(desktop): 让未识别的 Linux 桌面会话能保存登录

elfcv2f86174ea313
diff --git a/apps/desktop/src/main/__tests__/authCredentialLoginRecovery.test.ts b/apps/desktop/src/main/__tests__/authCredentialLoginRecovery.test.ts
index fadb657931..fec329845a 100644
--- a/apps/desktop/src/main/__tests__/authCredentialLoginRecovery.test.ts
+++ b/apps/desktop/src/main/__tests__/authCredentialLoginRecovery.test.ts
@@ -3,6 +3,7 @@ import { ScriptTarget, transpileModule } from 'typescript';
import { describe, expect, it, vi } from 'vitest';
import { AuthApiError as ClientAuthApiError } from '@cindy/auth-client';
import { loginPreparingErrorState } from '../../shared/authIpc';
+import { linuxCredentialFailureFields } from '../linuxPasswordStore.js';
import { mapLoginProvidersLoadFailure } from '../authStartupGate';
// Execute the production login action and eligibility predicate without loading
@@ -34,10 +35,13 @@ function setup({
}
const previous = { step: 'verification-code', kind: 'email', identifier: '[email protected]' };
const backend = { available: !backendUnavailable };
+ const verifyCode = vi.fn(async () => ({ status: 'ok' }));
+ const requestCode = vi.fn(async () => undefined);
const deps = {
AuthApiError,
loginPreparingErrorState,
- createAuthClient: () => ({ verifyCode: vi.fn(async () => ({ status: 'ok' })) }),
+ linuxCredentialFailureFields,
+ createAuthClient: () => ({ verifyCode, requestCode }),
acceptLoginOutcome: vi.fn(async () => {
throw new AuthApiError(code);
}),
@@ -71,6 +75,11 @@ function setup({
if (code === 'CREDENTIAL_STORE_UNAVAILABLE') isCredentialEncryptionAvailable();
return originalAccept(...args);
};
+ function assertLoginFlowCurrent() {}
+ let discoveredMethods = [];
+ function reduceAuthFlow(state, event) {
+ return Object.assign({ step: 'code-requested' }, event);
+ }
async function loadLoginProviders() {
loginFlowState = { step: 'identifier', providers: {} };
return loginFlowState;
@@ -86,6 +95,8 @@ function setup({
...new Function(...Object.keys(deps), compiled)(...Object.values(deps)),
previous,
backend,
+ verifyCode,
+ requestCode,
};
}
@@ -145,7 +156,12 @@ describe('credential failure during fresh sign-in', () => {
});
it('keeps the deadline in a terminal action error state for renderer reload', async () => {
- const harness = setup({ code: 'RATE_LIMITED', retryAt: 1_800_000_000_000, initialError: true });
+ const harness = setup({
+ code: 'RATE_LIMITED',
+ retryAt: 1_800_000_000_000,
+ initialError: true,
+ backendUnavailable: false,
+ });
const result = await harness.run({
type: 'verify-code',
kind: 'email',
@@ -156,7 +172,11 @@ describe('credential failure during fresh sign-in', () => {
});
it('passes the server cooldown without triggering credential recovery or dropping the form', async () => {
- const harness = setup({ code: 'RATE_LIMITED', retryAt: 1_800_000_000_000 });
+ const harness = setup({
+ code: 'RATE_LIMITED',
+ retryAt: 1_800_000_000_000,
+ backendUnavailable: false,
+ });
const result = await harness.run({
type: 'verify-code',
kind: 'email',
@@ -199,7 +219,7 @@ describe('credential failure during fresh sign-in', () => {
it.each(['INVALID_CODE', 'NETWORK_ERROR'])(
'keeps the form for %s without requesting process recovery',
async (code) => {
- const harness = setup({ code });
+ const harness = setup({ code, backendUnavailable: false });
const result = await harness.run({
type: 'verify-code',
kind: 'email',
@@ -210,4 +230,56 @@ describe('credential failure during fresh sign-in', () => {
expect(harness.needsRecovery()).toBe(false);
},
);
+
+ it('does not consume a verification code when encryption is unavailable', async () => {
+ const harness = setup();
+ const result = await harness.run({
+ type: 'verify-code',
+ kind: 'email',
+ identifier: '[email protected]',
+ code: '123456',
+ });
+ expect(harness.verifyCode).not.toHaveBeenCalled();
+ expect(result).toEqual({
+ success: false,
+ code: 'CREDENTIAL_STORE_UNAVAILABLE',
+ state: { step: 'error', code: 'CREDENTIAL_STORE_UNAVAILABLE', recoverTo: 'identifier' },
+ });
+ });
+
+ it('does not open the browser when encryption is unavailable', async () => {
+ const harness = setup();
+ const result = await harness.run({
+ type: 'start-browser',
+ kind: 'social',
+ providerOrConnectionId: 'google',
+ label: 'Google',
+ });
+ expect(result.code).toBe('CREDENTIAL_STORE_UNAVAILABLE');
+ expect(result.state).toEqual({
+ step: 'error',
+ code: 'CREDENTIAL_STORE_UNAVAILABLE',
+ recoverTo: 'identifier',
+ });
+ });
+
+ it('does not request a code when encryption is unavailable, but still does when it is available', async () => {
+ const blocked = setup();
+ const blockedResult = await blocked.run({
+ type: 'request-code',
+ kind: 'email',
+ identifier: '[email protected]',
+ });
+ expect(blocked.requestCode).not.toHaveBeenCalled();
+ expect(blockedResult.code).toBe('CREDENTIAL_STORE_UNAVAILABLE');
+
+ const ready = setup({ backendUnavailable: false });
+ const readyResult = await ready.run({
+ type: 'request-code',
+ kind: 'email',
+ identifier: '[email protected]',
+ });
+ expect(ready.requestCode).toHaveBeenCalledOnce();
+ expect(readyResult.success).toBe(true);
+ });
});
diff --git a/apps/desktop/src/main/__tests__/linuxPasswordStore.test.ts b/apps/desktop/src/main/__tests__/linuxPasswordStore.test.ts
index be2ecb369d..953e04f173 100644
--- a/apps/desktop/src/main/__tests__/linuxPasswordStore.test.ts
+++ b/apps/desktop/src/main/__tests__/linuxPasswordStore.test.ts
@@ -1,9 +1,15 @@
import { describe, expect, it, vi } from 'vitest';
-import { configureLinuxPasswordStore, linuxPasswordStoreRelaunchArgs } from '../linuxPasswordStore.js';
+import {
+ configureLinuxPasswordStore,
+ linuxCredentialFailureFields,
+ linuxPasswordStoreRelaunchArgs,
+} from '../linuxPasswordStore.js';
describe('Linux secure storage startup policy', () => {
it('preserves the backend on relaunch without forwarding arbitrary arguments', () => {
- expect(linuxPasswordStoreRelaunchArgs('gnome-libsecret')).toEqual(['--password-store=gnome-libsecret']);
+ expect(linuxPasswordStoreRelaunchArgs('gnome-libsecret')).toEqual([
+ '--password-store=gnome-libsecret',
+ ]);
expect(linuxPasswordStoreRelaunchArgs('kwallet6')).toEqual(['--password-store=kwallet6']);
expect(linuxPasswordStoreRelaunchArgs('')).toEqual([]);
expect(linuxPasswordStoreRelaunchArgs('gnome-libsecret --no-sandbox')).toEqual([]);
@@ -26,7 +32,7 @@ function configure(
return { switches, appendSwitch };
}
-describe('Hyprland password store startup selection', () => {
+describe('Linux password store startup selection', () => {
it.each([
{ XDG_CURRENT_DESKTOP: 'Hyprland' },
{ XDG_CURRENT_DESKTOP: 'Hyprland:wlroots' },
@@ -34,7 +40,14 @@ describe('Hyprland password store startup selection', () => {
{ XDG_SESSION_DESKTOP: 'Hyprland' },
{ DESKTOP_SESSION: 'hyprland' },
{ XDG_CURRENT_DESKTOP: ' ', XDG_SESSION_DESKTOP: 'Hyprland' },
- ])('selects libsecret for %j', (env) => {
+ { XDG_CURRENT_DESKTOP: 'labwc' },
+ { XDG_CURRENT_DESKTOP: 'labwc:wlroots' },
+ { XDG_CURRENT_DESKTOP: ' Labwc ' },
+ { XDG_SESSION_DESKTOP: 'labwc' },
+ {},
+ { XDG_CURRENT_DESKTOP: ' ' },
+ { XDG_SESSION_TYPE: 'wayland' },
+ ])('selects libsecret when Chromium would miss Secret Service: %j', (env) => {
const { switches, appendSwitch } = configure(env);
expect(switches.get('password-store')).toBe('gnome-libsecret');
expect(appendSwitch).toHaveBeenCalledExactlyOnceWith('password-store', 'gnome-libsecret');
@@ -43,31 +56,85 @@ describe('Hyprland password store startup selection', () => {
it.each(['kwallet', 'kwallet5', 'kwallet6', 'gnome-libsecret', 'basic', ''])(
'preserves an explicit --password-store=%s, including an empty switch',
(store) => {
- const { switches, appendSwitch } = configure(
- { XDG_CURRENT_DESKTOP: 'Hyprland' },
- 'linux',
- store,
- );
+ const { switches, appendSwitch } = configure({}, 'linux', store);
expect(switches.get('password-store')).toBe(store);
expect(appendSwitch).not.toHaveBeenCalled();
},
);
it.each([
- {},
{ XDG_CURRENT_DESKTOP: 'GNOME', DESKTOP_SESSION: 'hyprland' },
{ XDG_CURRENT_DESKTOP: 'KDE', XDG_SESSION_DESKTOP: 'Hyprland' },
+ { XDG_CURRENT_DESKTOP: 'XFCE' },
+ { XDG_CURRENT_DESKTOP: 'Unity' },
+ { XDG_CURRENT_DESKTOP: 'X-Cinnamon' },
+ { XDG_CURRENT_DESKTOP: 'Pantheon' },
+ { XDG_CURRENT_DESKTOP: 'UKUI' },
+ { XDG_CURRENT_DESKTOP: 'Deepin' },
+ { XDG_CURRENT_DESKTOP: 'LXQt' },
{ XDG_CURRENT_DESKTOP: 'sway' },
{ XDG_CURRENT_DESKTOP: 'niri' },
+ { XDG_CURRENT_DESKTOP: 'wlroots' },
{ XDG_CURRENT_DESKTOP: 'not-hyprland' },
- { XDG_SESSION_TYPE: 'wayland' },
- ])('leaves other or unknown desktops to Electron: %j', (env) => {
+ ])('leaves recognized or other named desktops to Electron: %j', (env) => {
expect(configure(env).appendSwitch).not.toHaveBeenCalled();
});
it.each(['darwin', 'win32'] as const)('leaves %s unchanged', (platform) => {
+ expect(configure({}, platform).appendSwitch).not.toHaveBeenCalled();
+ });
+});
+
+describe('Linux credential failure diagnostics', () => {
+ it('logs only the backend, switch class, and presence booleans', () => {
+ const secret = 'secret-token-value';
+ const fields = linuxCredentialFailureFields({
+ platform: 'linux',
+ env: {
+ XDG_CURRENT_DESKTOP: 'labwc:wlroots',
+ DBUS_SESSION_BUS_ADDRESS: 'unix:path=/run/user/1000/bus-' + secret,
+ },
+ backend: 'gnome_libsecret',
+ passwordStoreSwitch: 'gnome-libsecret',
+ });
+ expect(fields).toEqual({
+ backend: 'gnome_libsecret',
+ passwordStore: 'gnome-libsecret',
+ desktopIdentityPresent: true,
+ sessionBusPresent: true,
+ });
+ expect(JSON.stringify(fields)).not.toContain(secret);
+ expect(JSON.stringify(fields)).not.toContain('labwc');
+ expect(JSON.stringify(fields)).not.toContain('unix:path');
+ });
+
+ it('does not echo an unexpected switch or backend, and omits non-Linux fields', () => {
+ expect(
+ linuxCredentialFailureFields({
+ platform: 'linux',
+ env: {},
+ backend: 'custom-' + 'secret',
+ passwordStoreSwitch: '/tmp/' + 'secret',
+ }),
+ ).toEqual({
+ backend: 'unknown',
+ passwordStore: 'explicit',
+ desktopIdentityPresent: false,
+ sessionBusPresent: false,
+ });
+ expect(
+ linuxCredentialFailureFields({
+ platform: 'linux',
+ env: { XDG_CURRENT_DESKTOP: ' ', DBUS_SESSION_BUS_ADDRESS: ' ' },
+ }).desktopIdentityPresent,
+ ).toBe(false);
expect(
- configure({ XDG_CURRENT_DESKTOP: 'Hyprland' }, platform).appendSwitch,
- ).not.toHaveBeenCalled();
+ linuxCredentialFailureFields({
+ platform: 'darwin',
+ env: { XDG_CURRENT_DESKTOP: '', DBUS_SESSION_BUS_ADDRESS: 'unix:path=/tmp/bus' },
+ backend: 'gnome_libsecret',
+ passwordStoreSwitch: 'basic',
+ }),
+ ).toEqual({});
});
});
diff --git a/apps/desktop/src/main/authManager.ts b/apps/desktop/src/main/authManager.ts
index 4fdf28af39..fab2b7692b 100644
--- a/apps/desktop/src/main/authManager.ts
+++ b/apps/desktop/src/main/authManager.ts
@@ -46,6 +46,7 @@ import {
type SocialProvider,
} from '@cindy/auth-client';
import { readReloginFlag, clearReloginFlag, enableUncustomizedBetaChannel } from './updateService';
+import { linuxCredentialFailureFields } from './linuxPasswordStore.js';
import { probeBetaManifest } from './manifestService';
import { isEnableBetaUserCustomized, readUpdateChannelSettings } from './updateChannelStore';
import { BRAND_IDENTITY } from '@cindy/maker-shared/brand-identity';
@@ -554,10 +555,38 @@ function isCredentialEncryptionAvailable(): boolean {
} catch {
// Diagnostics must not change credential read behavior.
}
+ let backend: string | undefined;
+ try {
+ backend = (
+ safeStorage as { getSelectedStorageBackend?: () => string }
+ ).getSelectedStorageBackend?.();
+ } catch {
+ backend = 'unavailable';
+ }
+ let passwordStoreSwitch: string | undefined;
+ try {
+ const commandLine = (app as { commandLine?: { getSwitchValue?: (name: string) => string } })
+ .commandLine;
+ const fromCommandLine = commandLine?.getSwitchValue?.('password-store');
+ if (typeof fromCommandLine === 'string') passwordStoreSwitch = fromCommandLine;
+ } catch {
+ passwordStoreSwitch = undefined;
+ }
+ if (passwordStoreSwitch === undefined) {
+ const prefix = '--password-store=';
+ const arg = process.argv.find((item) => item.startsWith(prefix));
+ if (arg) passwordStoreSwitch = arg.slice(prefix.length);
+ }
log.warn('credential encryption backend unavailable', {
appReady: app.isReady(),
screenState,
electronVersion: process.versions.electron,
+ ...linuxCredentialFailureFields({
+ platform: process.platform,
+ env: process.env,
+ backend,
+ passwordStoreSwitch,
+ }),
});
}
return available;
@@ -722,16 +751,31 @@ function writeAtomicSafeCiphertext(key: string, ciphertext: string): boolean {
function isAtomicPersistedSecretAbsent(key: string): boolean {
if (!isCredentialEncryptionAvailable()) return false;
- const filepath = path.join(SAFE_STORAGE_DIR(), `${key}.enc`);
- for (const candidate of [filepath, `${filepath}.bak`]) {
+ return atomicPersistedSecretPresence(key) === 'absent';
+}
+
+/** File presence only. Encryption availability must not turn a missing file into an existing one. */
+function atomicPersistedSecretPresence(key: string): 'absent' | 'present' | 'unknown' {
+ const filepath = path.join(SAFE_STORAGE_DIR(), key + '.enc');
+ for (const candidate of [filepath, filepath + '.bak']) {
try {
fs.accessSync(candidate, fs.constants.F_OK);
- return false;
+ return 'present';
} catch (error) {
- if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') return false;
+ if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') return 'unknown';
}
}
- return true;
+ return 'absent';
+}
+
+function logUnreadableEncryptedRecord(
+ key: string,
+ presentMessage: string,
+ absentMessage: string,
+): void {
+ const absentAndUnavailable =
+ !isCredentialEncryptionAvailable() && atomicPersistedSecretPresence(key) === 'absent';
+ log.warn(absentAndUnavailable ? absentMessage : presentMessage);
}
function writeAtomicSafe(key: string, value: string): boolean {
@@ -861,7 +905,11 @@ function readAuthAccountLogoutTombstones(options: { recoverInvalid?: boolean } =
const raw = readAtomicSafe(AUTH_ACCOUNT_LOGOUT_TOMBSTONES_KEY);
if (raw === null) {
if (isAtomicPersistedSecretAbsent(AUTH_ACCOUNT_LOGOUT_TOMBSTONES_KEY)) return [];
- log.warn('encrypted auth logout tombstones are temporarily unreadable');
+ logUnreadableEncryptedRecord(
+ AUTH_ACCOUNT_LOGOUT_TOMBSTONES_KEY,
+ 'encrypted auth logout tombstones are temporarily unreadable',
+ 'encrypted auth logout tombstones are absent and the credential backend is unavailable',
+ );
if (options.recoverInvalid) return [];
throw new AuthApiError(
'CREDENTIAL_STORE_UNAVAILABLE',
@@ -972,7 +1020,11 @@ function readAuthAccountVault(
? { ...emptyAuthAccountVault(), loggedOutAccountKeys: persistedLogoutKeys }
: emptyAuthAccountVault();
}
- log.warn('encrypted auth account vault exists but is temporarily unreadable');
+ logUnreadableEncryptedRecord(
+ AUTH_ACCOUNT_VAULT_KEY,
+ 'encrypted auth account vault exists but is temporarily unreadable',
+ 'encrypted auth account vault is absent and the credential backend is unavailable',
+ );
if (options.allowUnreadable) return emptyAuthAccountVault();
throw new AuthApiError(
'CREDENTIAL_STORE_UNAVAILABLE',
@@ -5514,6 +5566,16 @@ async function runLoginAction(
const loginRealm = startsBuildRealmFlow ? AUTH_REGION : (pendingAuthRealm ?? activeAuthRealm);
const client = createAuthClient(loginRealm);
const stateBeforeAction = loginFlowState?.step === 'error' ? null : loginFlowState;
+ // User-triggered check of the already selected backend. Empty desktop identity
+ // is not itself a reason to refuse a code request or browser login.
+ const assertLoginCredentialStoreReady = (): void => {
+ if (isCredentialEncryptionAvailable()) return;
+ throw new AuthApiError(
+ 'CREDENTIAL_STORE_UNAVAILABLE',
+ 503,
+ 'Saved account credentials are temporarily unavailable',
+ );
+ };
try {
// Cancellation is intercepted by dispatchLoginAction so it can settle the
// already-running browser action instead of starting a second action.
@@ -5697,6 +5759,7 @@ async function runLoginAction(
if (action.kind === 'phone' && !providerConfig?.phone) {
throw new AuthApiError('PHONE_LOGIN_DISABLED', 400, 'Phone login is disabled');
}
+ assertLoginCredentialStoreReady();
await client.requestCode(action.kind, action.identifier, {
captchaToken: action.captchaToken,
});
@@ -5712,6 +5775,7 @@ async function runLoginAction(
}
if (action.type === 'verify-code') {
+ assertLoginCredentialStoreReady();
return {
success: true,
state: await acceptLoginOutcome(
@@ -5722,6 +5786,7 @@ async function runLoginAction(
}
if (action.type === 'start-browser') {
+ assertLoginCredentialStoreReady();
if (action.kind === 'social') {
const provider = action.providerOrConnectionId as SocialProvider;
if (!providerConfig?.social.includes(provider)) {
diff --git a/apps/desktop/src/main/linuxPasswordStore.ts b/apps/desktop/src/main/linuxPasswordStore.ts
index 1dd3fb7f2c..4090f1a26a 100644
--- a/apps/desktop/src/main/linuxPasswordStore.ts
+++ b/apps/desktop/src/main/linuxPasswordStore.ts
@@ -1,7 +1,49 @@
/** Preserve only the storage selector, not URLs or transient task arguments. */
export function linuxPasswordStoreRelaunchArgs(value: string): string[] {
return ['gnome-libsecret', 'kwallet', 'kwallet5', 'kwallet6', 'basic'].includes(value)
- ? [`--password-store=${value}`] : [];
+ ? ['--password-store=' + value]
+ : [];
+}
+
+const GNOME_LIBSECRET_DESKTOPS = new Set(['hyprland', 'labwc']);
+const KNOWN_PASSWORD_STORES = new Set([
+ 'gnome-libsecret',
+ 'kwallet',
+ 'kwallet5',
+ 'kwallet6',
+ 'basic',
+]);
+const KNOWN_STORAGE_BACKENDS = new Set([
+ 'basic_text',
+ 'gnome_libsecret',
+ 'kwallet',
+ 'kwallet5',
+ 'kwallet6',
+ 'unknown',
+ 'unavailable',
+]);
+
+/** First non-empty desktop identity. A session type is not a desktop name. */
+export function linuxDesktopIdentity(env: NodeJS.ProcessEnv): string {
+ return (
+ env.XDG_CURRENT_DESKTOP?.trim() ||
+ env.XDG_SESSION_DESKTOP?.trim() ||
+ env.DESKTOP_SESSION?.trim() ||
+ ''
+ );
+}
+
+/**
+ * Chromium only maps a few desktop names onto a secret store. Hyprland and
+ * labwc are not among them, so an unlocked Secret Service is never opened.
+ * An empty identity falls through to basic_text, which packaged builds refuse.
+ * Other named desktops, including sway and niri, stay with Electron.
+ */
+export function linuxDesktopNeedsGnomeLibsecret(identity: string): boolean {
+ if (!identity.trim()) return true;
+ return identity
+ .split(':')
+ .some((name) => GNOME_LIBSECRET_DESKTOPS.has(name.trim().toLowerCase()));
}
/** Configure before Electron's ready event, without probing or opening the keyring. */
@@ -18,16 +60,37 @@ export function configureLinuxPasswordStore({
};
}): void {
if (platform !== 'linux' || commandLine.hasSwitch('password-store')) return;
-
- // Chromium does not recognize Hyprland (including Omarchy) as a desktop
- // with a secret store. Prefer the active desktop over legacy session hints
- // so a stale DESKTOP_SESSION cannot override GNOME/KDE's native selection.
- const desktop =
- env.XDG_CURRENT_DESKTOP?.trim() ||
- env.XDG_SESSION_DESKTOP?.trim() ||
- env.DESKTOP_SESSION?.trim() ||
- '';
- if (desktop.split(':').some((name) => name.trim().toLowerCase() === 'hyprland')) {
+ // Prefer the active desktop over legacy session hints so a stale
+ // DESKTOP_SESSION cannot override GNOME/KDE's native selection.
+ if (linuxDesktopNeedsGnomeLibsecret(linuxDesktopIdentity(env))) {
commandLine.appendSwitch('password-store', 'gnome-libsecret');
}
}
+
+/** Never echo an unexpected switch value; it is not a credential, but it is untrusted. */
+export function redactPasswordStoreSwitch(value: string | undefined): string {
+ if (value === undefined) return 'unset';
+ if (value === '') return 'empty';
+ return KNOWN_PASSWORD_STORES.has(value) ? value : 'explicit';
+}
+
+export function redactStorageBackend(value: string | undefined): string {
+ if (!value) return 'unknown';
+ return KNOWN_STORAGE_BACKENDS.has(value) ? value : 'unknown';
+}
+
+/** Safe fields for a real credential failure. No desktop name, bus address, argv, or token. */
+export function linuxCredentialFailureFields(input: {
+ platform: NodeJS.Platform;
+ env: NodeJS.ProcessEnv;
+ backend?: string;
+ passwordStoreSwitch?: string;
+}): Record<string, string | boolean> {
+ if (input.platform !== 'linux') return {};
+ return {
+ backend: redactStorageBackend(input.backend),
+ passwordStore: redactPasswordStoreSwitch(input.passwordStoreSwitch),
+ desktopIdentityPresent: linuxDesktopIdentity(input.env).length > 0,
+ sessionBusPresent: Boolean(input.env.DBUS_SESSION_BUS_ADDRESS?.trim()),
+ };
+}
diff --git a/docs/dev-rules/credentials-and-local-storage.md b/docs/dev-rules/credentials-and-local-storage.md
index 73e4beae41..ebc6256f28 100644
--- a/docs/dev-rules/credentials-and-local-storage.md
+++ b/docs/dev-rules/credentials-and-local-storage.md
@@ -101,17 +101,26 @@ Claude.ai 登录,也不得收集、存储或中转订阅凭证。Cindy 因此
真实 CLI 的入口、项目设置、原生 / SDK hooks 与权限回归见
[smoke-claude-sdk.mjs](../../scripts/smoke-claude-sdk.mjs)。
-## Linux Hyprland / Omarchy 凭证后端
-
-- Desktop 在 Electron `ready` 之前为 Hyprland 默认选择 `gnome-libsecret`,避免桌面
- 自动识别失败导致登录回调收到令牌后无法加密保存。桌面身份依次取非空的
- `XDG_CURRENT_DESKTOP`、`XDG_SESSION_DESKTOP`、`DESKTOP_SESSION`;其他桌面保持
- Electron 原有选择。实现见
- [linuxPasswordStore.ts](../../apps/desktop/src/main/linuxPasswordStore.ts),回归见
+## Linux 凭证后端
+
+- Desktop 在 Electron `ready` 之前为 Hyprland、labwc,以及没有桌面身份的会话默认选择
+ `gnome-libsecret`。Chromium 不认识这些会话时会落到 `basic_text`,打包版会把它当成
+ 加密不可用,即使 Secret Service 已经解锁。桌面身份依次取非空的
+ `XDG_CURRENT_DESKTOP`、`XDG_SESSION_DESKTOP`、`DESKTOP_SESSION`。GNOME、KDE、XFCE
+ 等 Chromium 已能识别的桌面,以及 sway、niri 等未证实的命名桌面,保持 Electron 原有选择。
+ 实现见 [linuxPasswordStore.ts](../../apps/desktop/src/main/linuxPasswordStore.ts),回归见
[linuxPasswordStore.test.ts](../../apps/desktop/src/main/__tests__/linuxPasswordStore.test.ts)。
- 显式 `--password-store` 优先于此默认值。系统仍需提供可用且已解锁的 Secret Service
- (例如 GNOME Keyring);此修复不安装或解锁钥匙串,也不新增明文降级。现有仅限开发版的
+ (例如 GNOME Keyring);此修复不安装或解锁钥匙串,也不新增明文降级。libsecret 缺失时
+ Chromium 仍会回退,Cindy 继续拒绝明文。现有仅限开发版的
`XDT_DEV_SAFE_STORAGE_BASIC=1` 调试行为保持不变。
+- 不把空的桌面环境变量本身当成禁止登录的条件,也不在启动时探测钥匙串。用户发起验证码
+ 请求、验证码提交或浏览器登录时,才检查当前加密后端是否可用;不可用则返回既有的
+ `CREDENTIAL_STORE_UNAVAILABLE`,不发送验证码、不打开浏览器、不交换授权码。凭证读取
+ 失败时记录后端名称、`password-store` 开关类别,以及是否有桌面身份、是否有会话总线
+ 两个布尔值,不记录桌面名、总线地址、令牌或完整环境变量。加密不可用且 vault 或退出
+ 标记文件确实不存在时,日志说明记录缺席且后端不可用,仍抛出
+ `CREDENTIAL_STORE_UNAVAILABLE`,不把已有但暂时读不出的记录当成已删除。
- 旧版临时处理:完全退出 Cindy 后运行 `cindy --password-store=gnome-libsecret`。
实机验收需覆盖登录、退出应用后正常启动仍保持登录,以及 `cindy://` 回调启动路径。
diff --git a/docs/linux.md b/docs/linux.md
index 26a6a5bba5..b5e1870492 100644
--- a/docs/linux.md
+++ b/docs/linux.md
@@ -45,9 +45,14 @@ For Wayland screen sharing and file dialogs, keep your compositor's portal
backend and PipeWire installed and working. Omarchy normally configures these;
this installer deliberately does not rewrite Hyprland, PAM or portal settings.
See the [Electron safeStorage documentation](https://www.electronjs.org/docs/latest/api/safe-storage)
-for the backend model. KDE and GNOME retain Electron's existing selection;
-Hyprland selects `gnome-libsecret` before app readiness; other desktops retain
-Electron's selection. Desktop identity uses the first non-empty value from
+for the backend model. KDE, GNOME, XFCE and other recognized desktops retain
+Electron's existing selection. Before app readiness, Cindy selects
+`gnome-libsecret` for Hyprland, labwc, and a session with no desktop identity.
+Named desktops Chromium does not recognize, including sway and niri, keep
+Electron's selection. An empty identity otherwise falls back to `basic_text`,
+which a packaged build cannot use to save a login. Selecting libsecret does not
+install or unlock a keyring; if libsecret is missing, Chromium still falls back
+and Cindy refuses plaintext. Desktop identity uses the first non-empty value from
`XDG_CURRENT_DESKTOP`, `XDG_SESSION_DESKTOP`, and `DESKTOP_SESSION`.
An explicit `--password-store` always wins and survives an in-app update restart.