feat(desktop): persist mask + friendly keychain UX

Three changes end the "macOS asks for keychain password every time you
open Settings" complaint on unsigned builds:

1. Mask persistence — the Settings page was decrypting every stored
   secret just to render "sk-ant-…xyz9". Each decrypt triggers a
   keychain prompt on unsigned macOS builds, so users saw N prompts
   (one per provider) on every launch. Now the mask is computed at
   save time and stored alongside the ciphertext as `SecretRef.mask`.
   Settings reads it straight off disk, zero safeStorage calls. Legacy
   configs missing the field run a one-shot migration on first Settings
   open: decrypt once per provider to populate the mask, then persist.

2. First-run explainer (keychain-ux.ts) — before the first safeStorage
   prompt of the app's lifetime, show an in-app dialog explaining that
   macOS is about to ask for the login password, recommend "Always
   Allow", and reassure the user their key stays on-device. Flag
   persisted as a zero-byte file in userData so it only shows once ever.

3. Graceful degradation — when `safeStorage.isEncryptionAvailable()`
   returns false (most common cause: app running from a read-only DMG
   mount instead of /Applications), show a helpful dialog with
   actionable next steps and an "Open Applications folder" button,
   rather than throwing a bare "KEYCHAIN_UNAVAILABLE" to the renderer.
   Shown once per session to avoid modal spam. Import paths use a
   non-throwing `tryBuildSecretRef` so a broken keychain doesn't abort
   a multi-provider import — the rest of the config still lands, the
   user re-adds keys by hand.

All IPC handlers that touch safeStorage now go through a `withKeychain`
gate that calls `prepareKeychain` first; if encryption is unavailable,
the handler returns a user-friendly error instead of the bare throw.

- packages/shared/src/config.ts: SecretRef.mask?: string
- apps/desktop/src/main/keychain.ts: maskSecret, buildSecretRef,
  tryBuildSecretRef, migrateSecretMasks
- apps/desktop/src/main/provider-settings.ts: prefer stored mask
- apps/desktop/src/main/keychain-ux.ts: explainer + unavailable dialogs
- apps/desktop/src/main/onboarding-ipc.ts: withKeychain on 9 handlers

Author: hqhq1025

apps/desktop/src/main/keychain-ux.ts

@@ -0,0 +1,138 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { app, dialog, safeStorage, shell } from './electron-runtime';
+import { getLogger } from './logger';
+
+/**
+ * Keychain UX layer. Wraps the raw `safeStorage` calls with two one-time
+ * dialogs to turn the default macOS experience (opaque "password required"
+ * modal appearing with no context) into something a non-technical user can
+ * reason about.
+ *
+ *   (C) Friendly explainer — before the first keychain prompt of the app's
+ *       lifetime, show an in-app message telling the user macOS is about
+ *       to ask for their login password and recommending they click
+ *       "Always Allow" so it doesn't repeat. Flag stored as a zero-byte
+ *       file in userData so it persists across launches.
+ *
+ *   (E) Graceful degradation — when `safeStorage.isEncryptionAvailable()`
+ *       returns false (most commonly the app is running from a read-only
+ *       DMG mount instead of /Applications, so Electron can't establish a
+ *       keychain trust entry), surface a helpful dialog with a button to
+ *       open the Applications folder and quit. Shown at most once per
+ *       session — subsequent calls re-throw silently so we don't spam the
+ *       user with modals if they dismiss it.
+ */
+
+const log = getLogger('keychain-ux');
+
+const EXPLAINER_FLAG_FILE = 'keychain-explainer-seen';
+
+let unavailableDialogShownThisSession = false;
+
+function explainerFlagPath(): string {
+  return join(app.getPath('userData'), EXPLAINER_FLAG_FILE);
+}
+
+function hasSeenExplainer(): boolean {
+  try {
+    return existsSync(explainerFlagPath());
+  } catch {
+    return false;
+  }
+}
+
+function markExplainerSeen(): void {
+  try {
+    writeFileSync(explainerFlagPath(), '', { flag: 'w' });
+  } catch (err) {
+    log.warn('[keychain-ux] failed to persist explainer flag', err);
+  }
+}
+
+/**
+ * Show the first-time keychain explainer. Blocks until dismissed. Safe to
+ * call unconditionally — returns immediately if the user has already seen
+ * it on any prior launch.
+ */
+export async function maybeShowKeychainExplainer(): Promise<void> {
+  if (hasSeenExplainer()) return;
+  // Only relevant when safeStorage will actually prompt (macOS / Linux
+  // with a working keychain). If encryption isn't even available, the
+  // unavailable dialog handles the UX — skip the explainer.
+  if (!safeStorage.isEncryptionAvailable()) return;
+
+  try {
+    await dialog.showMessageBox({
+      type: 'info',
+      title: 'Open CoDesign 需要使用系统钥匙串',
+      message: '你的 API key 将会加密存在你自己的电脑上',
+      detail: [
+        'macOS 接下来会弹出一个系统窗口，问你是否允许 Open CoDesign 访问钥匙串。',
+        '',
+        '请点「始终允许」（Always Allow）— 之后 Open CoDesign 就不会再问了。',
+        '',
+        '你的 key 只在你本机保存，不会上传到任何云服务。',
+      ].join('\n'),
+      buttons: ['我知道了'],
+      defaultId: 0,
+    });
+  } catch (err) {
+    log.warn('[keychain-ux] explainer dialog failed', err);
+  }
+  markExplainerSeen();
+}
+
+/**
+ * Show the "keychain unavailable" dialog with actionable next steps. Shown
+ * at most once per session to avoid modal spam. Callers should treat this
+ * as advisory and still surface the underlying error to the user so
+ * failing IPC handlers return something the renderer can render.
+ */
+export async function maybeShowKeychainUnavailableDialog(): Promise<void> {
+  if (unavailableDialogShownThisSession) return;
+  unavailableDialogShownThisSession = true;
+
+  const fromDmg = process.execPath.includes('/Volumes/');
+  try {
+    const response = await dialog.showMessageBox({
+      type: 'warning',
+      title: '系统钥匙串不可用',
+      message: '无法加密保存你的 API key',
+      detail: [
+        fromDmg
+          ? '最常见原因：你直接从 DMG 运行了 Open CoDesign，没有拖到「应用程序」文件夹。'
+          : '系统钥匙串当前无法访问。可能是 macOS 权限未授权，或者 Open CoDesign 不在「应用程序」文件夹中。',
+        '',
+        '解决办法：',
+        '1. 退出 Open CoDesign（Cmd+Q）',
+        '2. 把 Open CoDesign.app 拖到「应用程序」文件夹',
+        '3. 从「应用程序」启动',
+        '',
+        '之后第一次启动 macOS 会请求权限，请选「始终允许」。',
+      ].join('\n'),
+      buttons: ['打开「应用程序」文件夹', '先不管，继续使用'],
+      defaultId: 0,
+      cancelId: 1,
+    });
+    if (response.response === 0) {
+      await shell.openPath('/Applications');
+    }
+  } catch (err) {
+    log.warn('[keychain-ux] unavailable dialog failed', err);
+  }
+}
+
+/**
+ * Preflight for any IPC handler that is about to encrypt or decrypt. Returns
+ * `true` when keychain ops should proceed, `false` when the caller should
+ * abort the operation (unavailable dialog will have been shown).
+ */
+export async function prepareKeychain(): Promise<boolean> {
+  if (!safeStorage.isEncryptionAvailable()) {
+    await maybeShowKeychainUnavailableDialog();
+    return false;
+  }
+  await maybeShowKeychainExplainer();
+  return true;
+}

apps/desktop/src/main/keychain.ts

@@ -1,4 +1,4 @@
-import { CodesignError } from '@open-codesign/shared';
+import { CodesignError, type Config, type SecretRef } from '@open-codesign/shared';
 import { safeStorage } from './electron-runtime';
 
 export function ensureKeychainAvailable(): void {
@@ -27,3 +27,86 @@ export function decryptSecret(ciphertextBase64: string): string {
   const buf = Buffer.from(ciphertextBase64, 'base64');
   return safeStorage.decryptString(buf);
 }
+
+/**
+ * Derive a display-safe mask for a secret — e.g. "sk-ant-***xyz9". Stored
+ * alongside the ciphertext so Settings can render the provider row without
+ * invoking `safeStorage.decryptString` (which prompts for the keychain
+ * password on unsigned macOS builds).
+ */
+export function maskSecret(plaintext: string): string {
+  if (plaintext.length <= 8) return '***';
+  const prefix = plaintext.startsWith('sk-') ? 'sk-' : plaintext.slice(0, 4);
+  const suffix = plaintext.slice(-4);
+  return `${prefix}***${suffix}`;
+}
+
+/**
+ * Convenience wrapper: encrypt a plaintext API key and return the full
+ * `SecretRef` (ciphertext + mask) in one shot. Use this at every save site
+ * so mask metadata is always written. Older configs missing `mask` are
+ * migrated by `migrateSecretMasks` on first read.
+ */
+export function buildSecretRef(plaintext: string): SecretRef {
+  return {
+    ciphertext: encryptSecret(plaintext),
+    mask: maskSecret(plaintext),
+  };
+}
+
+/**
+ * Non-throwing variant of `buildSecretRef` — returns `null` when safeStorage
+ * is unavailable (unsigned macOS without keychain entitlements, Linux
+ * without a secret-service daemon, etc.). Callers should skip persisting
+ * the secret and surface a warning so the REST of the imported config
+ * still lands; the user can re-add the key by hand once keychain is fixed.
+ *
+ * Only `KEYCHAIN_UNAVAILABLE` is caught — real unexpected errors still
+ * propagate so they're not silently swallowed.
+ */
+export function tryBuildSecretRef(plaintext: string): SecretRef | null {
+  try {
+    return buildSecretRef(plaintext);
+  } catch (err) {
+    if (err instanceof CodesignError && err.code === 'KEYCHAIN_UNAVAILABLE') {
+      return null;
+    }
+    throw err;
+  }
+}
+
+/**
+ * One-shot migration: for any secret missing the `mask` field, decrypt it
+ * once and populate the mask. Designed to run on config load — after this
+ * pass, `toProviderRows` never touches safeStorage again. Returns the
+ * migrated config plus a flag indicating whether anything changed (so the
+ * caller can decide whether to persist).
+ *
+ * Each decrypt-for-migration triggers exactly one keychain prompt per
+ * provider on unsigned macOS builds — unavoidable since we have to read
+ * the plaintext once to derive the mask. This is a one-time cost; all
+ * future launches read masks directly from disk.
+ *
+ * Robust to partial failures: if a single provider fails to decrypt (e.g.
+ * keychain revoked access mid-migration), we leave that row's mask
+ * unset and carry on with the rest.
+ */
+export function migrateSecretMasks(cfg: Config): { config: Config; changed: boolean } {
+  const secrets = cfg.secrets ?? {};
+  const entries = Object.entries(secrets);
+  const needs = entries.filter(([, ref]) => ref.mask === undefined || ref.mask.length === 0);
+  if (needs.length === 0) return { config: cfg, changed: false };
+
+  const nextSecrets: Record<string, SecretRef> = { ...secrets };
+  let changed = false;
+  for (const [provider, ref] of needs) {
+    try {
+      const plain = decryptSecret(ref.ciphertext);
+      nextSecrets[provider] = { ...ref, mask: maskSecret(plain) };
+      changed = true;
+    } catch {
+      /* skip — row will retry on next boot or when user edits it */
+    }
+  }
+  return { config: { ...cfg, secrets: nextSecrets }, changed };
+}

apps/desktop/src/main/onboarding-ipc.test.ts

@@ -59,6 +59,26 @@ vi.mock('./config', () => ({
 vi.mock('./keychain', () => ({
   encryptSecret: vi.fn((s: string) => `enc:${s}`),
   decryptSecret: vi.fn((s: string) => s.replace('enc:', '')),
+  maskSecret: vi.fn((s: string) => (s.length > 8 ? `${s.slice(0, 4)}***${s.slice(-4)}` : '***')),
+  buildSecretRef: vi.fn((s: string) => ({
+    ciphertext: `enc:${s}`,
+    mask: s.length > 8 ? `${s.slice(0, 4)}***${s.slice(-4)}` : '***',
+  })),
+  tryBuildSecretRef: vi.fn((s: string) => ({
+    ciphertext: `enc:${s}`,
+    mask: s.length > 8 ? `${s.slice(0, 4)}***${s.slice(-4)}` : '***',
+  })),
+  migrateSecretMasks: vi.fn((cfg: { secrets?: Record<string, unknown> }) => ({
+    config: cfg,
+    changed: false,
+  })),
+  ensureKeychainAvailable: vi.fn(() => {}),
+}));
+
+vi.mock('./keychain-ux', () => ({
+  prepareKeychain: vi.fn(async () => true),
+  maybeShowKeychainExplainer: vi.fn(async () => {}),
+  maybeShowKeychainUnavailableDialog: vi.fn(async () => {}),
 }));
 
 vi.mock('./storage-settings', () => ({