cc-viewer 1.9.0 → 1.9.2

package/server/lib/chat-queue.js

@@ -67,11 +67,12 @@ function _broadcast() {
   catch (err) { reportSwallowed('chat-queue.broadcast', err); }
 }
 
-function _makeItem(text) {
+function _makeItem(text, anchor) {
   return {
     id: 'q_' + Date.now().toString(36) + '_' + Math.random().toString(36).slice(2, 8),
     text,
     ts: Date.now(),
+    anchor: anchor || null,   // { project, sessionId } from the enqueueing client (2026-10-05)
   };
 }
 
@@ -95,6 +96,13 @@ function _clearEscTimer() {
  * NOTE 2: `isStreaming` (streamingState.active) flickers false between tool calls mid-turn;
  * injecting into that gap is harmless (the TUI natively queues the paste) but it means an
  * "immediate" inject can land inside the current turn's chain — accepted risk class.
+ * KNOWN LIMITATION (multi-project, 2026-10-05): the busy gate is global/bound-scoped —
+ * `isStreaming` reads the bound project's streamingState and `getPtyKind` follows the
+ * global active PTY, and `_items` is a single FIFO across projects. A message queued on
+ * project A can be head-of-line blocked by (or misjudge the busyness of) project B.
+ * Injection itself IS anchor-routed (item.anchor), so a queued message still lands on
+ * the project it was written in; only the timing/busy heuristic is not per-project.
+ * Per-project streaming state + queue isolation is a follow-up.
  */
 function _safeToInject() {
   if (!_deps) return false;
@@ -126,7 +134,12 @@ function _injectHead() {
   _injecting = true;
   const gen = _gen; // invalidate on clear()/stop(): a stale completion must not re-park
   try {
-    _deps.writeToPtySequential(bracketPasteSubmit(item.text), (ok) => {
+    // Route the inject by the enqueueing client's anchor when one was captured,
+    // so a message queued while viewing project A never lands in project B's PTY.
+    const _write = _deps.writeToPtySequentialFor && item.anchor
+      ? (chunks, done, opts) => _deps.writeToPtySequentialFor(chunks, done, opts, item.anchor)
+      : _deps.writeToPtySequential;
+    _write(bracketPasteSubmit(item.text), (ok) => {
       _injecting = false;
       if (gen !== _gen) return;
       if (!ok) {
@@ -175,7 +188,7 @@ function _pollUntilSafe(fn, onTimeout) {
  * `\x1b[201~` would otherwise break the paste frame), broadcasts, and arms a rescue timer for
  * the stale-busy case (frontend's isStreaming lags the real turn end by up to its debounce).
  */
-export function enqueue(text) {
+export function enqueue(text, anchor) {
   if (!_deps) return null;
   const clean = sanitizeInbound(text == null ? '' : String(text)).trim();
   if (!clean) return null;
@@ -186,7 +199,7 @@ export function enqueue(text) {
     catch (err) { reportSwallowed('chat-queue.reject-broadcast', err); }
     return null;
   }
-  const item = _makeItem(clean);
+  const item = _makeItem(clean, anchor);
   _items.push(item);
   _clearRescueTimer();
   _broadcast();
@@ -335,6 +348,56 @@ export function stop() {
   _gen++;
 }
 
+const RESUME_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * True /resume (2026-10-06): inject `/resume <uuid>` into a target project's running claude
+ * PTY so the process switches INTO that session in place (Claude Code's native SessionStart
+ * hook then re-binds the v2 writer via beginResumeSwitch). This is the in-process switch —
+ * NOT a respawn — and must only happen when the TUI is observably idle.
+ *
+ * Promise-returning so the route can map the outcome to HTTP. Resolves:
+ *   { ok:true }                 — the paste was written
+ *   { ok:false, reason:'busy' } — TUI streaming / approval open / another inject or poll in
+ *                                 flight / timed out waiting for idle (never blind-injects)
+ *   { ok:false, reason:'bad-uuid' }     — sessionUuid is not a UUID shape
+ *   { ok:false, reason:'no-deps' }      — initChatQueue never ran (SDK mode / not wired)
+ *   { ok:false, reason:'write-failed' } — the PTY write failed or threw
+ *
+ * Shares the single `_injecting`/`_pollTimer` slots with the drain/sendNow paths, so it
+ * refuses up-front when either is owned (mirrors sendNow's guard) instead of clobbering a
+ * pending drain timer and stranding a queued message. The completion handler resets
+ * `_injecting` unconditionally (both callback and catch) so a mid-inject clear()/stop()
+ * generation bump can never wedge the queue.
+ */
+export function injectResumeCommand(sessionUuid, anchor) {
+  return new Promise((resolve) => {
+    if (!_deps) { resolve({ ok: false, reason: 'no-deps' }); return; }
+    const uuid = sanitizeInbound(String(sessionUuid == null ? '' : sessionUuid)).trim();
+    if (!RESUME_UUID_RE.test(uuid)) { resolve({ ok: false, reason: 'bad-uuid' }); return; }
+    // Refuse BEFORE touching _pollUntilSafe: a drain's poll owns the single _pollTimer slot,
+    // and an in-flight inject owns _injecting — barging in would strand a queued message.
+    if (_injecting || _pollTimer) { resolve({ ok: false, reason: 'busy' }); return; }
+    let settled = false;
+    const done = (r) => { if (!settled) { settled = true; resolve(r); } };
+    const inject = () => {
+      _injecting = true;
+      try {
+        _deps.writeToPtySequentialFor(bracketPasteSubmit(`/resume ${uuid}`), (ok) => {
+          _injecting = false;
+          done(ok ? { ok: true } : { ok: false, reason: 'write-failed' });
+        }, { settleMs: 250 }, anchor || {});
+      } catch (err) {
+        _injecting = false;
+        reportSwallowed('chat-queue.resume.inject', err);
+        done({ ok: false, reason: 'write-failed' });
+      }
+    };
+    if (_safeToInject()) { inject(); return; }
+    _pollUntilSafe(inject, () => done({ ok: false, reason: 'busy' }));
+  });
+}
+
 export function __resetForTests() {
   stop();
   _deps = null;

package/server/lib/config-backup.js

@@ -1,13 +1,16 @@
 // 启动期配置备份 — 2026-06-06 LOG_DIR 整树删除事故防再犯。
-// preferences.json(auth/IM token/偏好)、profile.json(代理热切换)、workspaces.json(工作区注册表)
-// 是无法从日志/会话重建的"静态设置";本模块在 server 启动时把它们备份到 LOG_DIR **之外**
-// 的兄弟目录(默认 ~/.claude/cc-viewer-config-backups/<时间戳>/),滚动保留最近 KEEP 份。
-// 全程 best-effort:任何失败只返回 {ok:false},绝不抛错阻塞启动。
+// preferences.json(auth/IM/偏好)、profile.json(代理热切换)、workspaces.json(工作区注册表)、
+// credentials.json + master.key(凭证 vault 密文与主密钥) 是无法从日志/会话重建的"静态设置";
+// 本模块在 server 启动时把它们备份到 LOG_DIR **之外**的兄弟目录
+// (默认 ~/.claude/cc-viewer-config-backups/<时间戳>/),滚动保留最近 KEEP 份。
+// master.key 一并备份:credentials.json 是密文,没有 key 就是废数据;二者同地 0600,恢复路径才完整。
+// 历史明文备份(迁移前含 base64/明文密钥的 preferences/profile)不自动删除——它们是唯一的老密钥
+// 恢复来源,在确认 vault 可读前绝不清理。全程 best-effort:任何失败只返回 {ok:false},绝不抛错阻塞启动。
 import { existsSync, mkdirSync, copyFileSync, readdirSync, rmSync, chmodSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { LOG_DIR } from '../../findcc.js';
 
-const CONFIG_FILES = ['preferences.json', 'profile.json', 'workspaces.json'];
+const CONFIG_FILES = ['preferences.json', 'profile.json', 'workspaces.json', 'credentials.json', 'master.key'];
 const KEEP = 10;
 // 备份子目录名:严格时间戳形态。prune 只删匹配此形态的目录,绝不波及其它内容。
 const STAMP_RE = /^\d{8}_\d{6}$/;

package/server/lib/credential-access.js

@@ -0,0 +1,233 @@
+// Credential access layer — the single place config modules touch the vault.
+//
+// credential-vault.js / credential-store.js are pure path-injected primitives; this module is
+// the seam that binds them to cc-viewer's data root and encodes the cross-cutting rules that
+// every credential class shares, so auth.js / im-config.js / interceptor.js / preferences.js
+// don't each re-derive (and mis-derive) them:
+//
+//   1. ONE credential root, captured at module load. PROFILE_PATH is frozen at load
+//      (interceptor.js) and the vault is frozen alongside it; LOG_DIR is a live binding (setLogDir)
+//      that a logDir move (ccv --log-dir at runtime, POST /api/preferences {logDir}) can change.
+//      A frozen vault does NOT follow that move — which is the SAFE half of the trade: after a
+//      logDir switch the reader still finds the vault at the ORIGINAL root and the gate keeps
+//      working. (A live/following vault would resolve at the NEW, empty root while preferences.json
+//      is carried over with auth.enabled=true → password resolves '' → LAN gate opens. That
+//      fail-open is why the root is deliberately NOT live-bound; see the 739f49a6 re-review.)
+//   2. master.key is created ONLY when the vault is empty/absent. A read path that finds
+//      ciphertext but no key must hard-fail (unreadable), never mint a fresh key that orphans
+//      every existing secret.
+//   3. "Unreadable" is a first-class outcome, distinct from "absent". The LAN password gate
+//      treats an empty password as allow-all (auth.js), so a decrypt failure must surface as
+//      unreadable=true — never as ''.
+//
+// Boundary: L1-lib (imports json-store + credential-store/vault + findcc for the load-time root).
+import { existsSync, readFileSync } from 'node:fs';
+import { reportSwallowed } from '@ccv/core/error-report';
+import { LOG_DIR } from '../../findcc.js';
+import {
+  setSecret, getSecret, hasSecret, deleteSecret, credentialsFileFor, masterKeyPathFor, vaultUnreadable,
+} from './credential-store.js';
+import { _resetKeyCache } from './credential-vault.js';
+
+// Captured at module load — deliberately NOT a live binding. See header note (1).
+const CREDENTIALS_FILE = credentialsFileFor(LOG_DIR);
+const MASTER_KEY_PATH = masterKeyPathFor(LOG_DIR);
+
+export function getCredentialsFile() { return CREDENTIALS_FILE; }
+export function getMasterKeyPath() { return MASTER_KEY_PATH; }
+
+/** True when the vault holds at least one entry (so a missing master.key is a hard error). */
+function _vaultHasEntries() {
+  try {
+    if (!existsSync(CREDENTIALS_FILE)) return false;
+    const data = JSON.parse(readFileSync(CREDENTIALS_FILE, 'utf-8'));
+    return !!(data && typeof data === 'object' && data.creds && Object.keys(data.creds).length > 0);
+  } catch { return false; }
+}
+
+/** True when credentials.json exists but cannot be parsed — the fail-CLOSED signal (P0-A). */
+function _vaultUnreadable() {
+  return vaultUnreadable(CREDENTIALS_FILE);
+}
+
+/**
+ * Guard the key-creation rule. Returns { ok:true } when a key may be used/created, or
+ * { ok:false, reason } when ciphertext exists (or the vault is unreadable) but the key is gone
+ * (hard-fail — do not mint). An unreadable vault is treated as "has entries": minting a fresh
+ * key over it would let the next write overwrite ciphertext we can no longer read.
+ */
+function _keyUsable() {
+  if (existsSync(MASTER_KEY_PATH)) return { ok: true };
+  if (_vaultUnreadable()) {
+    return { ok: false, reason: 'master.key is missing and credentials.json is unreadable; refusing to mint (would orphan existing ciphertext)' };
+  }
+  if (_vaultHasEntries()) {
+    return { ok: false, reason: 'master.key is missing but credentials.json holds entries; refusing to mint a new key (existing secrets would be orphaned)' };
+  }
+  return { ok: true }; // empty/absent vault → first-ever key may be created on demand
+}
+
+/**
+ * Read a secret back to plaintext.
+ * Returns { value: string, unreadable: boolean }.
+ *   - vault entry decrypts → { value, unreadable:false }
+ *   - no vault entry → { value: fallbackPlain ?? '', unreadable:false } (legacy/pre-migration)
+ *   - vault entry exists but key/decrypt fails → { value: fallbackPlain ?? '', unreadable:true }
+ *   - the vault FILE itself is unreadable/corrupt → { value: fallbackPlain ?? '', unreadable:true }
+ * `fallbackPlain` is the caller's legacy on-disk value (plaintext or already-base64-DECODED),
+ * used only when there is no readable vault entry (the one-version read-fallback).
+ */
+export function readSecretOr(kind, ref, fallbackPlain = '') {
+  try {
+    // Fail-closed on an unreadable vault FILE (P0-A): hasSecret below would report "no entry"
+    // (readJsonSafe swallows the parse error → {}), and a gate that treats empty as allow-all
+    // would then open. Surface unreadable so callers deny / drop instead.
+    if (_vaultUnreadable()) {
+      return { value: fallbackPlain || '', unreadable: true };
+    }
+    if (!hasSecret(CREDENTIALS_FILE, kind, ref)) {
+      return { value: fallbackPlain || '', unreadable: false };
+    }
+    const usable = _keyUsable();
+    if (!usable.ok) {
+      reportSwallowed('credential-access.key-unusable', new Error(usable.reason));
+      return { value: fallbackPlain || '', unreadable: true };
+    }
+    const value = getSecret(CREDENTIALS_FILE, MASTER_KEY_PATH, kind, ref);
+    return { value, unreadable: false };
+  } catch (err) {
+    // Tampered ciphertext / wrong key / IO error → unreadable, never '' silently.
+    reportSwallowed('credential-access.read', err);
+    return { value: fallbackPlain || '', unreadable: true };
+  }
+}
+
+/**
+ * Write a secret to the vault. `plain` empty removes the entry. Returns true on success; on
+ * failure reports and returns false (callers must NOT then strip the legacy field).
+ */
+export function writeSecret(kind, ref, plain) {
+  try {
+    const usable = _keyUsable();
+    if (!usable.ok) {
+      reportSwallowed('credential-access.key-unusable', new Error(usable.reason));
+      return false;
+    }
+    setSecret(CREDENTIALS_FILE, MASTER_KEY_PATH, kind, ref, plain);
+    return true;
+  } catch (err) {
+    reportSwallowed('credential-access.write', err);
+    return false;
+  }
+}
+
+/** Remove a secret. Returns true on success. */
+export function removeSecret(kind, ref) {
+  try {
+    deleteSecret(CREDENTIALS_FILE, kind, ref);
+    return true;
+  } catch (err) {
+    reportSwallowed('credential-access.remove', err);
+    return false;
+  }
+}
+
+/**
+ * Idempotent one-field migration with read-back verification (the data-safety invariant):
+ *   a) if the legacy plaintext is empty → nothing to do, return { migrated:false, cleared:false }.
+ *   b) write the plaintext to the vault, then READ IT BACK and compare. Only when the read-back
+ *      matches do we say it is safe to clear the legacy field.
+ *   c) if the vault already holds a DIFFERENT value, the on-disk plaintext is the user's later
+ *      intent (hand-edit / restored backup / old binary) → it wins and overwrites the vault.
+ * `clearLegacy()` is invoked by the CALLER only when this returns { migrated:true, cleared:ok }
+ * — it performs the source-file strip inside the caller's own file lock. We never clear here.
+ * Returns { migrated:boolean, verified:boolean }.
+ */
+export function migrateFieldWithVerify(kind, ref, legacyPlain) {
+  if (!legacyPlain) return { migrated: false, verified: false };
+  try {
+    // If the vault already holds this exact value, nothing to write.
+    if (hasSecret(CREDENTIALS_FILE, kind, ref)) {
+      const existing = getSecret(CREDENTIALS_FILE, MASTER_KEY_PATH, kind, ref);
+      if (existing === legacyPlain) return { migrated: true, verified: true };
+      // Differing value: fall through and let the on-disk plaintext overwrite (user's later intent).
+    }
+    if (!writeSecret(kind, ref, legacyPlain)) return { migrated: false, verified: false };
+    const readBack = getSecret(CREDENTIALS_FILE, MASTER_KEY_PATH, kind, ref);
+    if (readBack !== legacyPlain) {
+      reportSwallowed('credential-access.migrate-verify', new Error(`read-back mismatch for ${kind}:${ref}`));
+      return { migrated: false, verified: false };
+    }
+    return { migrated: true, verified: true };
+  } catch (err) {
+    reportSwallowed('credential-access.migrate', err);
+    return { migrated: false, verified: false };
+  }
+}
+
+/** Test hook: drop cached key state so a fresh root/key is picked up per test. */
+export function _resetCredentialAccess() {
+  _resetKeyCache(); // clear all cached keys across roots (test hook / root change)
+}
+
+/**
+ * Persist the apiKeys of an incoming profile list into the vault, and return the list with
+ * apiKey STRIPPED for writing to profile.json (the file must never carry the key again).
+ *
+ * Per profile (kind=profile-apiKey, ref=profile.id):
+ *   - masked value (isMaskedFn true) → the client echoed the mask back unchanged: DO NOT touch
+ *     the vault entry (preserves the existing key) and do not write the sentinel anywhere.
+ *   - non-empty plaintext → writeSecret into the vault.
+ *   - empty/absent → the profile genuinely has no key: remove the vault entry.
+ * Profiles removed from the list (present in `existingProfiles` but absent in `incomingProfiles`)
+ * have their vault entry deleted — but only for a FULL-REPLACEMENT write (pass the on-disk list),
+ * never for a merge (cc-switch import passes no existingProfiles → no deletion).
+ *
+ * Returns the stripped list (apiKey:'') to persist in profile.json.
+ */
+export function persistProfilesApiKeys(incomingProfiles, existingProfiles, { isMaskedFn } = {}) {
+  const isMasked = typeof isMaskedFn === 'function' ? isMaskedFn : () => false;
+  const existingById = new Map((Array.isArray(existingProfiles) ? existingProfiles : [])
+    .filter(p => p && typeof p.id === 'string').map(p => [p.id, p]));
+  const incomingIds = new Set();
+  const stripped = (Array.isArray(incomingProfiles) ? incomingProfiles : []).map((p) => {
+    if (!p || typeof p.id !== 'string') return p;
+    incomingIds.add(p.id);
+    const key = typeof p.apiKey === 'string' ? p.apiKey : '';
+    if (key && isMasked(key)) {
+      // masked echo → the client didn't change the key, so preserve the existing one. Normally the
+      // vault already holds it (leave it untouched). But a profile.json that still carries a
+      // PLAINTEXT key (pre-migration) has no vault entry yet — migrate that plaintext in now,
+      // otherwise stripping the field below would lose the only copy. If that rescue write FAILS
+      // (vault unusable), keep the on-disk plaintext rather than stripping it into oblivion.
+      if (!hasSecret(getCredentialsFile(), 'profile-apiKey', p.id)) {
+        const legacyPlain = existingById.get(p.id)?.apiKey;
+        if (legacyPlain && !isMasked(legacyPlain)) {
+          const ok = writeSecret('profile-apiKey', p.id, legacyPlain);
+          if (!ok) return { ...p, apiKey: legacyPlain }; // vault write failed → keep the on-disk key
+        }
+      }
+      return { ...p, apiKey: '' };
+    }
+    if (key) {
+      // New plaintext → vault. On failure keep the plaintext on disk (do NOT strip): mirroring the
+      // auth/IM "preserve legacy on failed vault write" rule, so the key is never lost.
+      const ok = writeSecret('profile-apiKey', p.id, key);
+      return ok ? { ...p, apiKey: '' } : { ...p, apiKey: key };
+    }
+    // Empty key: preserve any existing vault entry. An empty apiKey here usually means the key
+    // simply wasn't served (an unreadable vault hydrates ''), so deleting on empty would destroy
+    // the real ciphertext on a no-op save. A profile's key is removed only by removing the whole
+    // profile (the full-replacement diff below), never by an empty-string inference.
+    return { ...p, apiKey: '' };
+  });
+  // Full-replacement: delete vault entries for profiles no longer in the list.
+  if (Array.isArray(existingProfiles)) {
+    for (const old of existingProfiles) {
+      if (old && typeof old.id === 'string' && !incomingIds.has(old.id)) {
+        removeSecret('profile-apiKey', old.id);
+      }
+    }
+  }
+  return stripped;
+}

package/server/lib/credential-migrate.js

@@ -0,0 +1,147 @@
+// One-time credential migration — moves legacy plaintext/base64 secrets into the vault.
+//
+// Runs ONCE at server startup (fire-and-forget setImmediate, after config-backup so a pre-strip
+// copy exists). For each legacy secret field it: writes the value to the vault, READS IT BACK and
+// compares (the data-safety invariant), and only then strips the legacy field from the source
+// file — all inside the source file's lock. Idempotent by data, not by a marker: a field that
+// already matches the vault is a no-op; a field whose on-disk value DIFFERS from the vault wins
+// (it is the user's later intent — hand edit / restored backup / old binary) and overwrites.
+//
+// The migration marker written at the end is INFORMATIONAL only (for logging + the backup-clean
+// decision); it never gates re-migration, so a later plaintext reintroduction is still picked up.
+//
+// Boundary: L1-lib. Imports json-store + credential-access + findcc (load-time root).
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { reportSwallowed } from '@ccv/core/error-report';
+import { LOG_DIR } from '../../findcc.js';
+import { mutateJsonSync } from './json-store.js';
+import { migrateFieldWithVerify, getCredentialsFile } from './credential-access.js';
+import { refFor as authRefFor } from './auth.js';
+import { secretRef as imSecretRef } from './im/im-config.js';
+
+// Load-time roots, aligned with credential-access / PROFILE_PATH (not live-bound).
+const PREFS_FILE = join(LOG_DIR, 'preferences.json');
+const PROFILE_FILE = join(LOG_DIR, 'profile.json');
+
+// Ref builders are imported from the OWNING runtime modules (auth.js refFor / im-config secretRef)
+// so the migrated entries are keyed EXACTLY as the runtime readers expect — a hand-copied format
+// here would silently orphan every migrated secret on a one-char divergence.
+
+function _b64Decode(stored) {
+  if (!stored || typeof stored !== 'string') return '';
+  try { return Buffer.from(stored, 'base64').toString('utf-8'); } catch { return ''; }
+}
+
+// IM platform → secret field keys (mirrors im-config DESCRIPTORS; only `secret`-type fields).
+// cred fields (appKey/appId/botId) stay base64 — they are low-sensitivity and out of scope.
+const IM_SECRET_FIELDS = {
+  dingtalk: ['appSecret'],
+  feishu: ['appSecret'],
+  wecom: ['secret'],
+  discord: ['botToken'],
+};
+
+/**
+ * Migrate auth.password / authByProject.*.password (base64) into the vault, then strip them from
+ * preferences.json (leaving { enabled }).
+ * Returns { migrated, skipped, failed } counts.
+ */
+function migrateAuthPasswords() {
+  const result = { migrated: 0, skipped: 0, failed: 0 };
+  if (!existsSync(PREFS_FILE)) return result;
+  mutateJsonSync(PREFS_FILE, (prefs) => {
+    if (!prefs || typeof prefs !== 'object') return;
+    // global
+    if (prefs.auth && typeof prefs.auth === 'object' && prefs.auth.password) {
+      const plain = _b64Decode(prefs.auth.password);
+      const r = migrateFieldWithVerify('lan-password', authRefFor(null), plain);
+      if (r.migrated && r.verified) { delete prefs.auth.password; result.migrated++; }
+      else result.failed++;
+    }
+    // per-project
+    if (prefs.authByProject && typeof prefs.authByProject === 'object') {
+      for (const [dir, entry] of Object.entries(prefs.authByProject)) {
+        if (!entry || typeof entry !== 'object' || !entry.password) { result.skipped++; continue; }
+        const plain = _b64Decode(entry.password);
+        const r = migrateFieldWithVerify('lan-password', authRefFor(dir), plain);
+        if (r.migrated && r.verified) { delete entry.password; result.migrated++; }
+        else result.failed++;
+      }
+    }
+  }, { mode: 0o600 });
+  return result;
+}
+
+/**
+ * Migrate IM platform secret fields (base64) into the vault, then strip them (leaving '').
+ */
+function migrateImSecrets() {
+  const result = { migrated: 0, skipped: 0, failed: 0 };
+  if (!existsSync(PREFS_FILE)) return result;
+  mutateJsonSync(PREFS_FILE, (prefs) => {
+    if (!prefs || typeof prefs !== 'object') return;
+    for (const [platform, fields] of Object.entries(IM_SECRET_FIELDS)) {
+      const cfg = prefs[platform];
+      if (!cfg || typeof cfg !== 'object') { result.skipped += fields.length; continue; }
+      for (const fieldKey of fields) {
+        const stored = cfg[fieldKey];
+        if (!stored) { result.skipped++; continue; }
+        const plain = _b64Decode(stored);
+        const r = migrateFieldWithVerify('im-secret', imSecretRef(platform, fieldKey), plain);
+        if (r.migrated && r.verified) { cfg[fieldKey] = ''; result.migrated++; }
+        else result.failed++;
+      }
+    }
+  }, { mode: 0o600 });
+  return result;
+}
+
+/**
+ * Migrate profile.json plaintext apiKeys into the vault, then strip them (leaving '').
+ * Reads the file directly (the startup strip is the ONLY writer that removes the field).
+ */
+function migrateProfileApiKeys() {
+  const result = { migrated: 0, skipped: 0, failed: 0 };
+  if (!existsSync(PROFILE_FILE)) return result;
+  mutateJsonSync(PROFILE_FILE, (data) => {
+    if (!data || typeof data !== 'object' || !Array.isArray(data.profiles)) return;
+    for (const p of data.profiles) {
+      if (!p || typeof p.id !== 'string') { result.skipped++; continue; }
+      const plain = typeof p.apiKey === 'string' ? p.apiKey : '';
+      if (!plain) { result.skipped++; continue; }
+      const r = migrateFieldWithVerify('profile-apiKey', p.id, plain);
+      if (r.migrated && r.verified) { p.apiKey = ''; result.migrated++; }
+      else result.failed++;
+    }
+  }, { mode: 0o600, strictCorrupt: true }); // never overwrite a corrupt profile.json with a {} fallback
+  return result;
+}
+
+/**
+ * Run the full one-time migration. Best-effort: per-class failures are reported and counted,
+ * never thrown (a failed field keeps its legacy value, so nothing is lost and the next boot
+ * retries). Returns a summary; also writes an informational marker into credentials.json.
+ */
+export function migrateCredentialsToVault() {
+  const summary = { auth: null, im: null, profiles: null, ok: true };
+  try { summary.auth = migrateAuthPasswords(); } catch (e) { summary.ok = false; reportSwallowed('credential-migrate.auth', e); }
+  try { summary.im = migrateImSecrets(); } catch (e) { summary.ok = false; reportSwallowed('credential-migrate.im', e); }
+  try { summary.profiles = migrateProfileApiKeys(); } catch (e) { summary.ok = false; reportSwallowed('credential-migrate.profiles', e); }
+
+  const total = (s) => (s ? s.migrated + s.failed : 0);
+  const touched = total(summary.auth) + total(summary.im) + total(summary.profiles);
+  if (touched > 0) {
+    // Informational marker only — never used to gate re-migration.
+    try {
+      mutateJsonSync(getCredentialsFile(), (data) => {
+        if (data && typeof data === 'object') data._credsMigratedAt = new Date().toISOString();
+      }, { mode: 0o600, strictCorrupt: true });
+    } catch (e) { reportSwallowed('credential-migrate.marker', e); }
+    // Loud, single-line startup signal so an operator can see the vault came online.
+    console.error(`[cc-viewer] credential vault migration: auth=${fmt(summary.auth)} im=${fmt(summary.im)} profiles=${fmt(summary.profiles)}`);
+  }
+  return summary;
+}
+
+function fmt(s) { return s ? `${s.migrated} migrated/${s.failed} failed` : 'n/a'; }

package/server/lib/credential-store.js

@@ -0,0 +1,120 @@
+// Credential store — one encrypted home for cc-viewer's secrets, separate from plain config.
+//
+// Splitting secrets OUT of preferences.json / profile.json into their own credentials.json is
+// what makes them safe to handle differently: the plain config can sync freely, while secrets
+// live only as vault ciphertext (see credential-vault.js) in a 0600 file that is excluded from
+// config-backup. It also means a future "sync plain config" path never drags a key along by
+// accident — the secret is in a different file entirely.
+//
+// On-disk shape (credentials.json, 0600):
+//   { version: 1, creds: { "<kind>:<ref>": "<base64(iv|tag|ct)>" } }
+// kind ∈ profile-apiKey | lan-password | im-secret. ref scopes the secret (profile id /
+// project dir / "<platform>.<field>"). Values are ciphertext from credential-vault.
+//
+// Reads/writes go through the unified json-store kernel (sync locked atomic write), sharing the
+// same per-file lock discipline as every other config file. Path-injected; the caller supplies
+// both the credentials file and the master key path (both derive from LOG_DIR at the call site).
+import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { readJsonSafe, mutateJsonSync } from './json-store.js';
+import { encryptSecret, decryptSecret, looksEncrypted } from './credential-vault.js';
+
+const VERSION = 1;
+
+/** Compose the storage key for a secret. */
+export function credKey(kind, ref) { return `${kind}:${ref}`; }
+
+// Distinguish "credentials file is ABSENT" from "present but UNREADABLE/corrupt". Read paths
+// (hasSecret/getSecret) treat an unreadable file as "no entries", which is fail-OPEN for a gate
+// that treats empty as allow-all. vaultUnreadable() lets the access layer fail CLOSED instead.
+function _readCreds(file) {
+  const data = readJsonSafe(file, {});
+  return (data && typeof data === 'object' && data.creds && typeof data.creds === 'object')
+    ? data.creds
+    : {};
+}
+
+/**
+ * True when `file` exists but cannot be parsed as a credentials file (corrupt/torn/EACCES).
+ * Absent → false. This is the fail-closed signal: a vault that SHOULD have entries but can't be
+ * read must never be treated as "empty" (→ empty password / empty apiKey).
+ */
+export function vaultUnreadable(file) {
+  if (!existsSync(file)) return false;
+  try {
+    const data = JSON.parse(readFileSync(file, 'utf-8'));
+    // A parsed file is "readable" iff it is a plain object (it may simply have no creds yet).
+    return !(data && typeof data === 'object' && !Array.isArray(data));
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Store a secret. `plain` empty/'' removes the entry (secrets are deleted, never stored empty).
+ * Returns true on success.
+ */
+export function setSecret(file, keyPath, kind, ref, plain) {
+  const key = credKey(kind, ref);
+  // strictCorrupt: a corrupt credentials.json must never be overwritten by the fallback — losing
+  // the whole vault (every secret) is unacceptable, unlike a self-healing preferences.json.
+  mutateJsonSync(file, (data) => {
+    if (!data || typeof data !== 'object') data = {};
+    if (!data.creds || typeof data.creds !== 'object') data.creds = {};
+    if (!plain) {
+      delete data.creds[key];
+    } else {
+      data.creds[key] = encryptSecret(keyPath, plain);
+    }
+    data.version = VERSION;
+  }, { mode: 0o600, fallback: {}, strictCorrupt: true });
+  return true;
+}
+
+/**
+ * Read a secret back to plaintext. Returns '' when absent. Throws only on tampered/wrong-key
+ * ciphertext (auth-tag failure) — the caller decides whether that is fatal.
+ */
+export function getSecret(file, keyPath, kind, ref) {
+  const stored = _readCreds(file)[credKey(kind, ref)];
+  if (!stored) return '';
+  return decryptSecret(keyPath, stored);
+}
+
+/** Does a ciphertext entry exist for this secret? */
+export function hasSecret(file, kind, ref) {
+  return Boolean(_readCreds(file)[credKey(kind, ref)]);
+}
+
+/** Remove a secret. No-op if absent. */
+export function deleteSecret(file, kind, ref) {
+  const key = credKey(kind, ref);
+  mutateJsonSync(file, (data) => {
+    if (data && typeof data === 'object' && data.creds && typeof data.creds === 'object') {
+      delete data.creds[key];
+    }
+  }, { mode: 0o600, fallback: {}, strictCorrupt: true });
+}
+
+/**
+ * Idempotent one-time migration helper: given a legacy value (plaintext or base64), ensure a
+ * ciphertext entry exists. If the entry already holds ciphertext, leave it (idempotent). If the
+ * legacy value is empty, do nothing. Returns true if it wrote a NEW ciphertext entry.
+ * `decodeLegacy` turns the legacy on-disk value into plaintext (identity for plaintext fields,
+ * base64-decode for the base64 fields).
+ */
+export function migrateLegacySecret(file, keyPath, kind, ref, legacyOnDisk, decodeLegacy) {
+  if (!legacyOnDisk) return false;
+  if (hasSecret(file, kind, ref)) return false; // already migrated
+  const plain = decodeLegacy(legacyOnDisk);
+  if (!plain) return false;
+  setSecret(file, keyPath, kind, ref, plain);
+  return true;
+}
+
+// Re-export so migration callers can detect already-encrypted legacy values without a second import.
+export { looksEncrypted };
+
+/** Canonical paths for the credentials file and master key, derived from a data root. */
+export function credentialsFileFor(logDir) { return join(logDir, 'credentials.json'); }
+export function masterKeyPathFor(logDir) { return join(logDir, 'master.key'); }