cc-viewer 1.8.18 → 1.8.20

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'); }

package/server/lib/credential-vault.js

@@ -0,0 +1,112 @@
+// Credential vault — real at-rest encryption for cc-viewer's secrets.
+//
+// The legacy encodings were obfuscation, not security: profile.json held apiKeys in plaintext,
+// and the LAN password / IM app secrets were base64 inside preferences.json (trivially reversible;
+// the code comments said so themselves). This module upgrades them to AES-256-GCM with a
+// per-record random IV and a machine-local master key.
+//
+// Key model: a single 256-bit `master.key` (0600) generated on first use and stored next to the
+// data root. This is the standard trade-off for a headless background server (no interactive
+// passphrase prompt, no OS-keychain native dep). At-rest on a single machine it is inherently
+// bounded — anyone who reads BOTH master.key and the ciphertext can decrypt — but it raises the
+// bar from "plaintext / base64 in a world-readable-shape file" to "needs the key file too", and it
+// is the prerequisite for any cloud handling (only ciphertext, never plaintext, may leave the
+// machine; the master key never does).
+//
+// Boundary: L1-lib. Path-injected (no LOG_DIR import) so it stays a pure primitive.
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+
+const KEY_MODE = 0o600;
+const IV_BYTES = 12;   // GCM standard
+const TAG_BYTES = 16;  // GCM auth tag
+const KEY_BYTES = 32;  // AES-256
+
+// Process-local cache so we don't re-read/re-stat the key file on every encrypt. Keyed by the
+// master.key path so tests that redirect LOG_DIR get a fresh key per path.
+const _keyCache = new Map();
+
+/**
+ * Load (or lazily create) the master key at `keyPath`. Created with randomBytes(32) + 0600 on
+ * first use. Throws if the key file exists but is malformed (wrong length) — better to fail loud
+ * than silently re-derive and orphan existing ciphertext.
+ */
+export function loadMasterKey(keyPath) {
+  // Cache is only valid while the on-disk key still exists. If the key file was removed out
+  // from under us (a wipe of the data root, an OS cleanup), a stale cached key would let a
+  // writer re-encrypt with a key that no longer exists on disk — leaving ciphertext that a
+  // later cold process cannot read, and splitting state from _keyUsable()'s disk check.
+  if (_keyCache.has(keyPath) && existsSync(keyPath)) return _keyCache.get(keyPath);
+  _keyCache.delete(keyPath);
+  let key;
+  if (existsSync(keyPath)) {
+    const raw = readFileSync(keyPath);
+    // Stored raw (32 bytes). Tolerate a trailing newline for hand-inspectability.
+    const trimmed = raw.subarray(0, KEY_BYTES);
+    if (trimmed.length !== KEY_BYTES) {
+      throw new Error(`credential-vault: master key at ${keyPath} has ${trimmed.length} bytes, expected ${KEY_BYTES}`);
+    }
+    key = Buffer.from(trimmed);
+  } else {
+    key = randomBytes(KEY_BYTES);
+    mkdirSync(dirname(keyPath), { recursive: true, mode: 0o700 });
+    writeFileSync(keyPath, key, { mode: KEY_MODE });
+    try { chmodSync(keyPath, KEY_MODE); } catch { /* best-effort; non-POSIX */ }
+  }
+  _keyCache.set(keyPath, key);
+  return key;
+}
+
+/**
+ * Encrypt a UTF-8 secret → base64(iv | tag | ciphertext). Returns '' for empty input so callers
+ * can distinguish "no secret" from "a secret that decrypts to empty".
+ */
+export function encryptSecret(keyPath, plain) {
+  if (!plain) return '';
+  const key = loadMasterKey(keyPath);
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const ct = Buffer.concat([cipher.update(String(plain), 'utf-8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([iv, tag, ct]).toString('base64');
+}
+
+/**
+ * Decrypt a value produced by encryptSecret. Returns '' for empty input. Throws on malformed
+ * input or auth-tag mismatch (tampered / wrong key) — callers decide whether to fall back to a
+ * legacy encoding or surface the error.
+ */
+export function decryptSecret(keyPath, stored) {
+  if (!stored) return '';
+  const key = loadMasterKey(keyPath);
+  const buf = Buffer.from(String(stored), 'base64');
+  if (buf.length < IV_BYTES + TAG_BYTES) {
+    throw new Error('credential-vault: ciphertext too short');
+  }
+  const iv = buf.subarray(0, IV_BYTES);
+  const tag = buf.subarray(IV_BYTES, IV_BYTES + TAG_BYTES);
+  const ct = buf.subarray(IV_BYTES + TAG_BYTES);
+  const decipher = createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf-8');
+}
+
+/**
+ * Heuristic: does `stored` look like vault ciphertext (vs a legacy plaintext/base64 value)?
+ * Used by the one-time migration to detect already-migrated values. Not a security boundary —
+ * just a shape check (base64 that decodes to ≥ IV+TAG bytes).
+ */
+export function looksEncrypted(stored) {
+  if (!stored || typeof stored !== 'string') return false;
+  if (!/^[A-Za-z0-9+/=]+$/.test(stored)) return false;
+  let buf;
+  try { buf = Buffer.from(stored, 'base64'); } catch { return false; }
+  return buf.length >= IV_BYTES + TAG_BYTES + 1;
+}
+
+/** Test hook: drop the cached key for `keyPath` (or all) so a fresh one is (re)generated. */
+export function _resetKeyCache(keyPath) {
+  if (keyPath === undefined) _keyCache.clear();
+  else _keyCache.delete(keyPath);
+}

package/server/lib/file-access-policy.js

@@ -15,6 +15,7 @@ import { resolve, basename, sep, join } from 'node:path';
 import { homedir, platform, tmpdir } from 'node:os';
 import { getClaudeConfigDir, onLogDirChange } from '../../findcc.js';
 import { loadWorkspaces } from '../workspace-registry.js';
+import { getBackupRoot } from './config-backup.js';
 
 const osPlatform = platform();
 const isWin = osPlatform === 'win32';
@@ -91,6 +92,10 @@ const SENSITIVE_CLAUDE_FILES = new Set([
   '.credentials.json',
   'settings.json',
   'settings.local.json',
+  // cc-viewer 凭证 vault(credentials.json 密文)与主密钥(master.key):即使 ~/.claude 在 allowlist,
+  // 也绝不跨网读(master.key 同时被下方 .key 文件名规则覆盖,这里双保险)。
+  'credentials.json',
+  'master.key',
 ]);
 
 // ─── allowlist roots 缓存 ──────────────────────────────────────────────────────
@@ -205,6 +210,17 @@ export function isReadAllowed(absPath) {
     }
   }
 
+  // 2b) Deny the cc-viewer config-backup dir tree — every rolling backup holds credentials.json
+  // ciphertext + master.key, which together are the full decryption kit. The dir defaults to
+  // ~/.claude/cc-viewer-config-backups/ (a sibling of LOG_DIR), but it must be denied whenever it
+  // lands inside an allowlist root, regardless of whether LOG_DIR was moved.
+  try {
+    const backupReal = realpathSync(getBackupRoot());
+    if (isInsideRoot(real, backupReal)) {
+      return { ok: false, reason: 'sensitive-config-backup' };
+    }
+  } catch { /* backup root missing / not realpath-able → no extra deny */ }
+
   // 3) 项目内文件豁免 sensitive 文件名(允许 fixtures/test-cert.pem 等合法 fixture)
   const projectRoot = getProjectRoot();
   const isInProj = isInsideRoot(real, projectRoot);