cc-viewer 1.8.19 → 1.8.20

package/server/lib/im/im-config.js

@@ -11,8 +11,10 @@
 // (`secret`: appSecret) are both base64-encoded on disk so preferences.json never
 // shows them in literal plaintext. This is light obfuscation, NOT encryption. The
 // admin API masks secret fields entirely (→ hasSecret).
-import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { mutateJsonSync } from '../json-store.js';
+import { readSecretOr, writeSecret } from '../credential-access.js';
 import { LOG_DIR } from '../../../findcc.js';
 
 const MIN_CHUNK = 500;
@@ -130,16 +132,10 @@ function readPrefs() {
   }
 }
 
-function writePrefs(prefs) {
-  const p = getPrefsPath();
-  const dir = dirname(p);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
-  writeFileSync(p, JSON.stringify(prefs, null, 2), { mode: 0o600 });
-  // writeFileSync's mode only applies on creation; re-assert 0600 — the file now carries
-  // the (base64) secrets.
-  try { chmodSync(p, 0o600); } catch { /* best-effort; non-POSIX or race */ }
-}
-
+// Credential fields (`cred`: appKey/appId/botId, LOW sensitivity) stay base64 in preferences.json.
+// Secret fields (`secret`: appSecret/botToken) live in the encrypted credential vault
+// (credentials.json, AES-256-GCM) — never in preferences.json. The legacy base64 secret fields
+// are migrated out at startup and cleared. Secrets are keyed `<platform>.<field>`.
 export function encodeSecret(plain) {
   return plain ? Buffer.from(plain, 'utf-8').toString('base64') : '';
 }
@@ -148,6 +144,11 @@ export function decodeSecret(stored) {
   try { return Buffer.from(stored, 'base64').toString('utf-8'); } catch { return ''; }
 }
 
+// Vault ref for an IM platform secret field. Exported so the one-time migration
+// (credential-migrate.js) derives refs from the SAME source as the runtime readers — a divergence
+// would silently orphan every migrated secret.
+export function secretRef(id, fieldKey) { return `${id}.${fieldKey}`; }
+
 function clampChunk(n, dflt = DEFAULT_CHUNK) {
   const v = Number(n);
   if (!Number.isFinite(v)) return dflt; // missing/invalid → the field's default (per-platform, e.g. Discord 1900)
@@ -180,13 +181,19 @@ function normField(type, v, dflt) {
   }
 }
 
-function decodeField(type, v, dflt) {
-  switch (type) {
-    case 'cred':
-    case 'secret': return decodeSecret(v);
-    case 'bool': return v !== undefined && v !== null ? !!v : (dflt !== undefined ? !!dflt : false);
+function decodeField(id, f, v) {
+  switch (f.type) {
+    case 'secret': {
+      // Vault-first, legacy base64 as the one-version read-fallback. readSecretOr distinguishes
+      // "unreadable" (lost key / tampered) from "absent"; for a bridge secret, unreadable and
+      // absent both degrade to "bridge won't start" (hasCreds false) — a down bot, never a leak.
+      const legacyPlain = decodeSecret(v);
+      return readSecretOr('im-secret', secretRef(id, f.key), legacyPlain).value;
+    }
+    case 'cred': return decodeSecret(v);
+    case 'bool': return v !== undefined && v !== null ? !!v : (f.default !== undefined ? !!f.default : false);
     case 'idlist': return normalizeIdList(v);
-    case 'chunk': return clampChunk(v, dflt);
+    case 'chunk': return clampChunk(v, f.default);
     case 'region': return v === 'lark' ? 'lark' : 'feishu';
     default: return typeof v === 'string' ? v : '';
   }
@@ -204,15 +211,30 @@ export function normalize(id, cfg) {
 function decodeStored(id, stored) {
   const desc = DESCRIPTORS[id];
   const out = {};
-  for (const f of desc.fields) out[f.key] = decodeField(f.type, stored ? stored[f.key] : undefined, f.default);
+  for (const f of desc.fields) {
+    // No on-disk entry for this field → its default. For a secret that ALSO means "don't
+    // consult the vault": a stray vault entry must not resurrect a secret for a platform the
+    // prefs say nothing about (e.g. after preferences.json was wiped while credentials.json
+    // survived). Only a field actually present on disk resolves through the vault.
+    if (!stored || typeof stored !== 'object' || !(f.key in stored)) {
+      out[f.key] = normField(f.type, undefined, f.default);
+      continue;
+    }
+    out[f.key] = decodeField(id, f, stored[f.key]);
+  }
   return out;
 }
 
-function encodeForDisk(id, n) {
+// On-disk shape for preferences.json[platform]: cred fields stay base64; a secret field is
+// CLEARED (empty string) when the vault write succeeded, or kept as base64 when it failed (so
+// the secret is not lost). `cleared` maps fieldKey → bool per secret field.
+function encodeForDisk(id, n, cleared = {}) {
   const desc = DESCRIPTORS[id];
   const out = {};
   for (const f of desc.fields) {
-    out[f.key] = (f.type === 'cred' || f.type === 'secret') ? encodeSecret(n[f.key]) : n[f.key];
+    if (f.type === 'secret') out[f.key] = cleared[f.key] ? '' : encodeSecret(n[f.key]);
+    else if (f.type === 'cred') out[f.key] = encodeSecret(n[f.key]);
+    else out[f.key] = n[f.key];
   }
   return out;
 }
@@ -240,22 +262,50 @@ export function loadState(id) {
 
 /**
  * Persist a platform's config (read-merge-write, preserving all other prefs and other
- * platforms). If a secret field is empty AND a secret is already stored, the existing
- * secret is PRESERVED (lets the admin edit other fields without re-typing the secret).
- * To remove the secret, disable the bridge. Stored base64; returns the in-memory
- * (plaintext) normalized shape.
+ * platforms). Secret fields are written to the credential vault; if a secret field is empty
+ * AND a secret is already stored (in the vault), the existing secret is PRESERVED (lets the
+ * admin edit other fields without re-typing the secret). To remove the secret, disable the
+ * bridge. cred fields stay base64 in preferences.json. Returns the in-memory (plaintext)
+ * normalized shape.
  */
 export function saveConfig(id, cfg) {
   const desc = DESCRIPTORS[id];
-  const prefs = readPrefs();
   const normalized = normalize(id, cfg);
+  // Resolve each secret field's EFFECTIVE plaintext BEFORE writing. An empty field means "keep
+  // the stored one". The stored value may live in the VAULT and/or (pre-migration) in the legacy
+  // base64 preferences field — try the vault first, then the legacy field, so an unreadable vault
+  // (lost key / corrupt) never resolves a still-present legacy secret to empty and wipes it.
+  const legacyPlain = {};
+  const vaultUnreadableNoFallback = new Set();
+  mutateJsonSync(getPrefsPath(), (prefs) => {
+    const storedCfg = prefs[desc.prefKey];
+    for (const f of desc.fields) {
+      if (f.type !== 'secret') continue;
+      const ref = secretRef(id, f.key);
+      legacyPlain[f.key] = decodeSecret(storedCfg && storedCfg[f.key]);
+      if (!normalized[f.key]) {
+        const { value, unreadable } = readSecretOr('im-secret', ref, legacyPlain[f.key]);
+        if (value) normalized[f.key] = value;
+        else if (legacyPlain[f.key]) normalized[f.key] = legacyPlain[f.key];
+        else if (unreadable) vaultUnreadableNoFallback.add(f.key); // vault unreadable & nothing on disk
+      }
+    }
+  }, { mode: 0o600 });
+  // Write each resolved secret to the vault. A field whose vault write failed, or whose vault is
+  // unreadable with no legacy fallback, KEEPS its legacy base64 in preferences.json (secret not
+  // lost); only a field safely written to the vault is cleared from preferences.json.
+  const cleared = {};
   for (const f of desc.fields) {
-    if (f.type === 'secret' && !normalized[f.key]) {
-      const existing = decodeSecret(prefs[desc.prefKey] && prefs[desc.prefKey][f.key]);
-      if (existing) normalized[f.key] = existing;
+    if (f.type !== 'secret') continue;
+    const ref = secretRef(id, f.key);
+    if (vaultUnreadableNoFallback.has(f.key)) {
+      cleared[f.key] = false; // vault unreadable & no legacy copy → keep whatever is on disk
+    } else {
+      cleared[f.key] = normalized[f.key] ? writeSecret('im-secret', ref, normalized[f.key]) : true;
     }
   }
-  prefs[desc.prefKey] = encodeForDisk(id, normalized);
-  writePrefs(prefs);
+  mutateJsonSync(getPrefsPath(), (prefs) => {
+    prefs[desc.prefKey] = encodeForDisk(id, normalized, cleared);
+  }, { mode: 0o600 });
   return normalized;
 }

package/server/lib/im-deny.js

@@ -8,16 +8,25 @@
 // 注意：worker 的工作目录在 ~/.claude/cc-viewer/IM_<id>/ 下，因此**不能**整体封禁 ~/.claude，
 // 只精确保护其中的全局 settings/hooks 与 preferences.json（IM 密钥），其余留给 worker 正常读写。
 import os from 'node:os';
-import { resolve } from 'node:path';
+import { resolve, basename } from 'node:path';
 
 // 凭证目录：读 + 写都拒（含密钥/令牌）。
-const CRED_DIRS = ['.ssh', '.aws', '.gnupg', '.kube', '.docker', '.config/gcloud'];
+const CRED_DIRS = ['.ssh', '.aws', '.gnupg', '.kube', '.docker', '.config/gcloud', '.claude/cc-viewer-config-backups'];
 // 家目录下的 shell 启动文件：写拒（被改写可植入持久化）。
 const WRITE_HOME_FILES = ['.bashrc', '.zshrc', '.bash_profile', '.zprofile', '.zshenv', '.profile', '.npmrc', '.netrc'];
-// 精确文件：写拒（保护 deny 机制本身与 IM 密钥）。相对家目录。
-const WRITE_REL_PATHS = ['.claude/settings.json', '.claude/settings.local.json', '.claude/cc-viewer/preferences.json'];
-// 精确文件：读拒（含令牌/密钥）。相对家目录。
-const READ_REL_PATHS = ['.npmrc', '.netrc', '.claude/cc-viewer/preferences.json'];
+// Global settings/hooks: write-deny (protects the deny mechanism itself). Resolved against ~.
+const WRITE_REL_PATHS = ['.claude/settings.json', '.claude/settings.local.json', '.claude/cc-viewer/preferences.json', '.claude/cc-viewer/credentials.json', '.claude/cc-viewer/master.key'];
+// Token/secret files under home: read-deny. Resolved against ~.
+const READ_REL_PATHS = ['.npmrc', '.netrc', '.claude/cc-viewer/preferences.json', '.claude/cc-viewer/credentials.json', '.claude/cc-viewer/master.key'];
+
+// Vault file names (bare-name match, any directory): LOG_DIR can be moved by --log-dir /
+// POST /api/preferences {logDir}, so hardcoding ~/.claude/cc-viewer would lose the vault whenever
+// the root moves. Match by file name so it stays denied regardless of root. Case-insensitive and
+// EXACT (does NOT match .bak/.old/.txt suffix variants — those are covered by the Bash-layer /i
+// regex and the backup-dir rule); basename grabs the last segment across POSIX/win32 (pathOf's
+// resolve would make lastIndexOf('/') miss on win32 backslashes).
+const VAULT_FILE_RE = /^(credentials\.json|master\.key)$/i;
+function isVaultFile(abs) { return VAULT_FILE_RE.test(basename(abs)); }
 
 // Bash 命令硬拦截规则。每条 { re, reason }。
 const BASH_DENY_RULES = [
@@ -43,8 +52,11 @@ const BASH_DENY_RULES = [
   { re: /\b(curl|wget)\b[^\n]*\s-{1,2}(d|data|data-binary|data-raw|post-file|F|form|T|upload-file)\b/i, reason: 'outbound data upload (exfil risk)' },
   { re: /\b(curl|wget)\b[^\n]*@\//i, reason: 'outbound file upload (exfil risk)' },
   // 凭证 / 密钥文件访问（Bash 层；与下面 Read/Write 路径层互为补充——cat 等会绕过路径层）。
-  // 覆盖 SSH/AWS/GnuPG/k8s/docker/gcloud/gh/npm/netrc + cc-viewer 自身的 IM 密钥库 preferences.json + 全局 settings。
-  { re: /(id_rsa|id_ed25519|id_ecdsa|authorized_keys|\.ssh\/|\.aws\/|\.gnupg\/|\.kube\/|\.docker\/|\.config\/(gcloud|gh)\/|\.netrc|\.npmrc|cc-viewer\/preferences\.json|\.claude\/settings(\.local)?\.json)\b/i, reason: 'access to credential / secret files' },
+  // 覆盖 SSH/AWS/GnuPG/k8s/docker/gcloud/gh/npm/netrc + cc-viewer 自身的 IM 密钥库 preferences.json
+  // + 凭证 vault(credentials.json/master.key，含 cc-viewer-config-backups 备份目录) + 全局 settings。
+  // credentials.json/master.key 用裸文件名匹配(不限 cc-viewer/ 前缀),并含 cred*/master* glob 形式,
+  // 防止经备份目录、相对路径或 shell glob(cred*.json master*)绕过——IM 通道宁可拦多。
+  { re: /(id_rsa|id_ed25519|id_ecdsa|authorized_keys|\.ssh\/|\.aws\/|\.gnupg\/|\.kube\/|\.docker\/|\.config\/(gcloud|gh)\/|\.netrc|\.npmrc|cc-viewer\/preferences\.json|credentials\.json|master\.key|cc-viewer-config-backups|\.claude\/settings(\.local)?\.json)\b|(cred\*|master\*)/i, reason: 'access to credential / secret files' },
 ];
 
 function underAny(absPath, roots) {
@@ -82,6 +94,7 @@ export function evaluateImDeny(toolName, toolInput = {}, opts = {}) {
   if (toolName === 'Read') {
     const abs = pathOf(toolInput, home);
     if (!abs) return { deny: false };
+    if (isVaultFile(abs)) return { deny: true, reason: 'read of the credential vault / master key' };
     if (underAny(abs, credRoots)) return { deny: true, reason: 'read of a credential directory' };
     if (READ_REL_PATHS.some((rel) => abs === resolve(home, rel))) return { deny: true, reason: 'read of a secret/credential file' };
     return { deny: false };
@@ -90,6 +103,7 @@ export function evaluateImDeny(toolName, toolInput = {}, opts = {}) {
   if (toolName === 'Edit' || toolName === 'Write' || toolName === 'NotebookEdit') {
     const abs = pathOf(toolInput, home);
     if (!abs) return { deny: false };
+    if (isVaultFile(abs)) return { deny: true, reason: 'write to the credential vault / master key' };
     if (underAny(abs, credRoots)) return { deny: true, reason: 'write to a credential directory' };
     if (WRITE_HOME_FILES.some((f) => abs === resolve(home, f))) return { deny: true, reason: 'write to a shell startup / credential file' };
     if (WRITE_REL_PATHS.some((rel) => abs === resolve(home, rel))) return { deny: true, reason: 'write to protected global config (settings/hooks or IM secrets)' };

package/server/lib/json-store.js

@@ -0,0 +1,264 @@
+// Unified JSON store kernel — one locked + atomic read/write path per config file.
+//
+// cc-viewer historically copy-pasted the same "read → mutate → tmp→rename" block across
+// prefs-store / auth / im-config / workspace-registry / ask-store / session-pin-store, with
+// divergent lock and permission handling (and a few writers that were neither locked nor
+// atomic — see lib/im/im-config.js). This module extracts that pattern ONCE so the lock and
+// the 0600 policy live in a single place. It is the prerequisite for any consistent local
+// state (and, later, for cloud sync): a file cannot be projected or compared unless every
+// writer goes through the same locked, atomic path.
+//
+// Boundary: L1-lib. Imports only node builtins + the two L0-leaf primitives
+// (file-api.renameSyncWithRetry, async-file-lock.withFileLockAsync) + @ccv/core/error-report.
+// It deliberately does NOT import LOG_DIR — callers inject the file path so the kernel stays
+// a pure, reusable primitive with no data-root coupling.
+//
+// Two lock flavors are provided because callers split into two camps:
+//   - mutateJson      — async lock (withFileLockAsync), for async mutators.
+//   - mutateJsonSync  — synchronous spin lock (openSync('wx')), for the many existing SYNC
+//                       writers (auth.js, im-config.js) that cannot become async without
+//                       cascading signature changes through routes and server startup.
+// Both serialize same-process callers and mutex cross-process on the same `${file}.lock`.
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, unlinkSync, openSync, closeSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { renameSyncWithRetry } from './file-api.js';
+import { withFileLockAsync, hasLiveDiskHolder } from './async-file-lock.js';
+import { reportSwallowed } from '@ccv/core/error-report';
+
+/** Lock file lives next to the data file, derived from ITS name (not a fixed basename), so two
+ *  different files in the same directory never share a lock by accident. */
+export function lockPathFor(file) { return `${file}.lock`; }
+
+/**
+ * Tolerant JSON read. Missing / corrupt / non-object (when fallback is a plain object) → fallback.
+ * Arrays are accepted when the fallback is an array; a scalar never satisfies an object fallback.
+ */
+export function readJsonSafe(file, fallback = {}) {
+  try {
+    if (!existsSync(file)) return fallback;
+    const obj = JSON.parse(readFileSync(file, 'utf-8'));
+    if (obj === null || typeof obj !== 'object') return fallback;
+    // Shape guard: an array fallback accepts only an array; a plain-object fallback rejects one.
+    if (Array.isArray(fallback) !== Array.isArray(obj)) return fallback;
+    return obj;
+  } catch {
+    return fallback;
+  }
+}
+
+// Sentinel for "file exists but cannot be read/parsed". A MUTATE path can choose how to treat it:
+//   - DEFAULT (tolerant): collapse to `fallback` and write, so a corrupt preferences.json stays
+//     self-healing (the long-standing L66 behavior — a user re-saving recovers the file).
+//   - strictCorrupt:true: refuse to write, preserving the corrupt bytes — for files whose loss is
+//     unacceptable (e.g. profile.json, where a {} overwrite would drop every profile).
+const CORRUPT = Symbol('json-store.corrupt');
+function _readForMutation(file, fallback) {
+  if (!existsSync(file)) return fallback; // genuinely absent → seeding is fine
+  try {
+    const obj = JSON.parse(readFileSync(file, 'utf-8'));
+    if (obj === null || typeof obj !== 'object') return CORRUPT;
+    if (Array.isArray(fallback) !== Array.isArray(obj)) return CORRUPT;
+    return obj;
+  } catch {
+    return CORRUPT;
+  }
+}
+
+function _resolveForMutation(data, file, strictCorrupt) {
+  if (data !== CORRUPT) return data;
+  if (strictCorrupt) {
+    const err = new Error(`json-store: refusing to overwrite corrupt/unreadable file ${file}`);
+    err.code = 'JSON_STORE_CORRUPT';
+    reportSwallowed('json-store.corrupt-guard', err);
+    throw err;
+  }
+  return undefined; // tolerant: signal "use the fallback"
+}
+
+/**
+ * Atomic write (tmp + renameSyncWithRetry). `mode` defaults to 0600 (the file may carry secrets);
+ * pass `mode: false` to skip the permission bit entirely (non-secret stores under umask).
+ * Serialization: `pretty` (2-space, the prefs convention) or compact.
+ */
+export function writeJsonAtomic(file, data, { mode = 0o600, pretty = true } = {}) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`;
+  try {
+    writeFileSync(tmp, pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data), mode ? { mode } : undefined);
+    renameSyncWithRetry(tmp, file);
+    if (mode) {
+      // writeFileSync's mode only applies on creation; re-assert on a pre-existing file.
+      try { chmodSync(file, mode); } catch { /* best-effort; non-POSIX or race */ }
+    }
+  } catch (err) {
+    try { unlinkSync(tmp); } catch {}
+    throw err;
+  }
+}
+
+/**
+ * Locked read-modify-write (async). Reads inside the lock, runs `mutator(data)` (mutate in
+ * place; may be async), atomically writes, returns the mutator's value when defined else data.
+ */
+export async function mutateJson(file, mutator, { mode = 0o600, pretty = true, fallback = {}, ensureDir, strictCorrupt = false } = {}) {
+  return withFileLockAsync(lockPathFor(file), async () => {
+    const resolved = _resolveForMutation(_readForMutation(file, fallback), file, strictCorrupt);
+    const data = resolved === undefined ? fallback : resolved;
+    const result = await mutator(data);
+    writeJsonAtomic(file, data, { mode, pretty });
+    return result !== undefined ? result : data;
+  }, { ensureDir: ensureDir ?? dirname(file) });
+}
+
+/**
+ * Lock-only primitive: holds the file's `${file}.lock` around `fn()` WITHOUT doing any read
+ * or write itself. For stores whose on-disk shape differs from their in-memory shape (e.g.
+ * ask-store's {version, entries} wrap) and therefore need to run their own domain read/save
+ * inside the mutex rather than the kernel's read→mutate→write. Shares the same lock as
+ * mutateJson / mutateJsonSync for the file.
+ */
+export async function withJsonLock(file, fn, { ensureDir } = {}) {
+  return withFileLockAsync(lockPathFor(file), fn, { ensureDir: ensureDir ?? dirname(file) });
+}
+
+// ─── Synchronous spin lock ───
+// Mirrors async-file-lock's two-tier stale detection (dead PID or aged mtime) but with
+// openSync('wx') + a blocking Atomics.wait so sync callers can hold the SAME `${file}.lock`.
+// Same-process serialization is inherent (JS is single-threaded; a sync critical section has
+// no interleaving). Cross-process mutual exclusion comes from the lock file.
+
+function _isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (err) { return err && err.code === 'EPERM'; }
+}
+
+function _readLockOwnerPid(path) {
+  try {
+    const raw = readFileSync(path, 'utf-8');
+    if (!raw) return null;
+    const obj = JSON.parse(raw);
+    if (obj && Number.isInteger(obj.pid)) return obj.pid;
+  } catch {}
+  return null;
+}
+
+function _isLockStale(path, mtimeFallbackMs) {
+  const pid = _readLockOwnerPid(path);
+  if (pid !== null) {
+    if (pid === process.pid) {
+      // Own pid is a crash leftover ONLY when this process does not currently hold the disk lock
+      // via the async flavor. An async holder (mutateJson / withJsonLock / mutatePrefs) is alive
+      // and mid-critical-section right now — it yields the JS thread at every await, so this sync
+      // caller can observe its lock; stealing it would let both writers commit and lose an update.
+      if (hasLiveDiskHolder(path)) return false;
+      return true;
+    }
+    return !_isPidAlive(pid);
+  }
+  try {
+    const stats = statSync(path);
+    return Date.now() - stats.mtimeMs > mtimeFallbackMs;
+  } catch {
+    return false; // conservative: cannot stat → assume held
+  }
+}
+
+function _blockingSleep(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch { /* Atomics.wait unavailable on the main thread in some embedders — best-effort */ }
+}
+
+// Returns true when the lock was acquired, false on timeout (caller decides how to degrade).
+// When the lock is held by THIS process's async flavor (mutateJson / withJsonLock / mutatePrefs),
+// the sync caller must NOT spin-then-degrade: the async holder is alive and mid-critical-section,
+// and a sync write issued from inside that critical section would alias the SAME in-memory object
+// the async holder is about to write back — so the sync update is silently lost (the exact failure
+// this kernel exists to prevent). That reentrancy is a programming error, not a race to ride out:
+// throw so the caller fails loudly instead of corrupting state. Foreign-process contention still
+// degrades per the caller's timeout policy.
+function _acquireLockSync(lockPath, { deadline = 2000, retryMs = 25, staleThresholdMs = 5000 } = {}) {
+  if (hasLiveDiskHolder(lockPath)) {
+    const err = new Error(`mutateJsonSync re-entered a lock held by this process's async flavor: ${lockPath}`);
+    err.code = 'JSON_STORE_REENTRANT';
+    reportSwallowed('json-store.reentrant-sync', err);
+    throw err;
+  }
+  const deadlineAt = Date.now() + deadline;
+  while (true) {
+    let fd;
+    try {
+      fd = openSync(lockPath, 'wx');
+      try { writeFileSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() })); } finally { closeSync(fd); }
+      return true;
+    } catch (err) {
+      if (err?.code === 'EEXIST') {
+        if (Date.now() < deadlineAt) {
+          if (_isLockStale(lockPath, staleThresholdMs)) {
+            try { unlinkSync(lockPath); } catch {}
+            continue;
+          }
+          _blockingSleep(retryMs);
+          continue;
+        }
+        if (_isLockStale(lockPath, staleThresholdMs)) {
+          try { unlinkSync(lockPath); } catch {}
+          continue;
+        }
+        return false; // timeout — caller degrades instead of crashing
+      }
+      throw err;
+    }
+  }
+}
+
+/**
+ * Synchronous locked read-modify-write, for the existing SYNC writers (auth.js, im-config.js).
+ * Holds the SAME `${file}.lock` as mutateJson so a sync writer and an async writer of the same
+ * file still mutex cross-process. `mutator` must be synchronous (no await).
+ *
+ * Timeout / reentrancy policy:
+ *  - Foreign process holds the lock and it cannot be acquired in time: DEGRADE to an unlocked
+ *    atomic write rather than throwing — a 2s freeze plus an uncaught throw out of a route
+ *    callback would kill the whole server. The atomic write still can't tear the file; the
+ *    residual lost-update window is the pre-kernel status quo and is reported so it's visible.
+ *    Pass { strict: true } to throw instead.
+ *  - THIS process's async flavor holds the lock (reentrant sync call from inside an async
+ *    critical section): THROW (JSON_STORE_REENTRANT). That write would alias the async holder's
+ *    in-memory object and be silently overwritten — a fail-closed throw is the only safe answer.
+ */
+export function mutateJsonSync(file, mutator, { mode = 0o600, pretty = true, fallback = {}, ensureDir, deadline, strict = false, strictCorrupt = false } = {}) {
+  const dir = ensureDir ?? dirname(file);
+  try { mkdirSync(dir, { recursive: true }); } catch {}
+  const lockPath = lockPathFor(file);
+  const acquired = _acquireLockSync(lockPath, deadline ? { deadline } : {});
+  if (!acquired && strict) {
+    throw new Error(`Lock acquisition timeout: ${lockPath} (held by live process)`);
+  }
+  if (!acquired) {
+    reportSwallowed('json-store.lock-timeout-degraded', new Error(`mutateJsonSync degraded to unlocked write: ${file}`));
+  }
+  try {
+    const resolved = _resolveForMutation(_readForMutation(file, fallback), file, strictCorrupt);
+    const data = resolved === undefined ? fallback : resolved;
+    const result = mutator(data);
+    writeJsonAtomic(file, data, { mode, pretty });
+    return result !== undefined ? result : data;
+  } finally {
+    if (acquired) {
+      try { unlinkSync(lockPath); } catch (err) { reportSwallowed('json-store.lock-release', err); }
+    }
+  }
+}
+
+/**
+ * Generic shallow merge of a patch onto `target` IN PLACE. Domain-specific merges (e.g.
+ * approvalModal reconciliation in prefs-store) stay in the per-store layer — the kernel only
+ * provides the plain-object assign so every store doesn't re-hand-roll it.
+ */
+export function applyJsonPatch(target, patch) {
+  if (!patch || typeof patch !== 'object') return target;
+  Object.assign(target, patch);
+  return target;
+}

package/server/lib/prefs-store.js

@@ -7,11 +7,8 @@
 // callers serialize via withFileLockAsync's per-lockPath Promise chain; cross-process
 // callers mutex on the lock file. This prevents a concurrent writer from clobbering the
 // password-bearing file or losing a fork update.
-import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, unlinkSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { randomBytes } from 'node:crypto';
-import { renameSyncWithRetry } from './file-api.js';
-import { withFileLockAsync } from './async-file-lock.js';
+import { mutateJson, readJsonSafe, writeJsonAtomic } from './json-store.js';
 import { mergeApprovalModalPrefs } from '@ccv/core/approval-modal-prefs';
 import { reconcileVoicePackPrefs } from './voice-pack-manager.js';
 import { LOG_DIR } from '../../findcc.js';
@@ -22,46 +19,24 @@ import { LOG_DIR } from '../../findcc.js';
 // override on the helpers below exists only so the preferences route can forward its
 // deps.getPrefsFile() seam (used by branch tests) and stay symmetric with the GET read.
 export function getPrefsFile() { return join(LOG_DIR, 'preferences.json'); }
-// Lock lives next to the file so every writer of the SAME preferences.json shares one lock
-// (global POST, fork ops, …). In prod all paths are canonical ⇒ one lock ⇒ serialized.
-function getPrefsLock(file) { return join(dirname(file), 'preferences.lock'); }
 
 /** Read the raw on-disk prefs object (no stripping, no virtual defaults). {} on miss/corrupt. */
 export function readPrefsRaw(file = getPrefsFile()) {
-  try {
-    if (!existsSync(file)) return {};
-    const obj = JSON.parse(readFileSync(file, 'utf-8'));
-    return obj && typeof obj === 'object' ? obj : {};
-  } catch { return {}; }
-}
-
-/** Atomic write (tmp + rename) with 0600 — the file may carry the base64 password. */
-function writePrefsAtomic(prefs, file) {
-  mkdirSync(dirname(file), { recursive: true });
-  const tmp = `${file}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`;
-  try {
-    writeFileSync(tmp, JSON.stringify(prefs, null, 2), { mode: 0o600 });
-    renameSyncWithRetry(tmp, file);
-    // writeFileSync's mode only applies on creation; re-assert 0600 on a pre-existing file.
-    try { chmodSync(file, 0o600); } catch { /* best-effort; non-POSIX or race */ }
-  } catch (err) {
-    try { unlinkSync(tmp); } catch {}
-    throw err;
-  }
+  return readJsonSafe(file, {});
 }
 
 /**
  * Locked read-modify-write. Reads the raw prefs inside the lock, runs mutator(prefs)
  * (mutate in place; may be async), atomically writes, and returns the mutator's return
  * value when defined, else the mutated prefs object. `file` defaults to the canonical path.
+ *
+ * Delegates to the unified json-store kernel (mutateJson): one async file lock derived from
+ * the file name + atomic tmp→rename at 0600. The lock is shared with the SYNC writers of the
+ * same file (auth.js / im-config.js via mutateJsonSync), so all preferences.json writers now
+ * mutex on the same `preferences.json.lock`.
  */
 export async function mutatePrefs(mutator, file = getPrefsFile()) {
-  return withFileLockAsync(getPrefsLock(file), async () => {
-    const prefs = readPrefsRaw(file);
-    const result = await mutator(prefs);
-    writePrefsAtomic(prefs, file);
-    return result !== undefined ? result : prefs;
-  }, { ensureDir: dirname(file) });
+  return mutateJson(file, mutator, { mode: 0o600, fallback: {}, ensureDir: dirname(file) });
 }
 
 /**

package/server/lib/session-pin-store.js

@@ -8,10 +8,9 @@
 // '' means no active project (workspace mode not yet launched) → read = null / write = no-op.
 // Writes are atomic (tmp + rename) so a torn read can't happen when several writers race
 // (mirrors server/lib/prefs-store.js).
-import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs';
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
-import { randomBytes } from 'node:crypto';
-import { renameSyncWithRetry } from './file-api.js';
+import { writeJsonAtomic } from './json-store.js';
 
 /** Pin file path inside the project dir: `.session-pin.json`. */
 export function pinFilePath(logDir) {
@@ -32,8 +31,10 @@ export function readPin(logDir) {
 
 /**
  * Write (or clear) the pinned session id. No project (logDir = '') → no-op, returns false.
- * A null/empty pinnedSessionId deletes the file (back to "show latest"). Atomic tmp+rename.
- * Returns true on success, false on no-project / write failure (view state is best-effort).
+ * A null/empty pinnedSessionId deletes the file (back to "show latest"). Atomic via the
+ * json-store kernel (tmp + rename). Non-secret → mode:false (umask); the pin is a view
+ * preference, not a credential. Returns true on success, false on no-project / write
+ * failure (view state is best-effort).
  */
 export function writePin(logDir, pinnedSessionId) {
   if (!logDir) return false;
@@ -44,15 +45,7 @@ export function writePin(logDir, pinnedSessionId) {
       try { unlinkSync(file); } catch { /* already absent */ }
       return true;
     }
-    mkdirSync(logDir, { recursive: true });
-    const tmp = `${file}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`;
-    try {
-      writeFileSync(tmp, JSON.stringify({ pinnedSessionId: id }));
-      renameSyncWithRetry(tmp, file);
-    } catch (err) {
-      try { unlinkSync(tmp); } catch {}
-      throw err;
-    }
+    writeJsonAtomic(file, { pinnedSessionId: id }, { mode: false, pretty: false });
     return true;
   } catch { return false; }
 }

package/server/pty-manager.js

@@ -353,13 +353,19 @@ async function _spawnClaudeImpl(proxyPort, cwd, extraArgs = [], claudePath = nul
         'Bash(git push:*)', 'Bash(npm publish:*)', 'Bash(ssh:*)', 'Bash(scp:*)',
         `Read(${home}/.ssh/**)`, `Edit(${home}/.ssh/**)`, `Write(${home}/.ssh/**)`,
         `Read(${home}/.aws/**)`, `Edit(${home}/.aws/**)`, `Write(${home}/.aws/**)`,
-        // File-precise: protect the deny mechanism itself (settings/hooks) and the IM
-        // credential store (preferences.json), but do not block all of ~/.claude — the
-        // worker's working directory sits under ~/.claude/cc-viewer/IM_<id>/ and must stay
-        // writable.
+        // File-precise: protect the deny mechanism itself (settings/hooks), the IM
+        // credential store (preferences.json), and the credential vault (credentials.json +
+        // master.key), but do not block all of ~/.claude — the worker's working directory
+        // sits under ~/.claude/cc-viewer/IM_<id>/ and must stay writable.
         `Edit(${home}/.claude/settings.json)`, `Write(${home}/.claude/settings.json)`,
         `Edit(${home}/.claude/settings.local.json)`, `Write(${home}/.claude/settings.local.json)`,
         `Edit(${home}/.claude/cc-viewer/preferences.json)`, `Write(${home}/.claude/cc-viewer/preferences.json)`,
+        `Read(${home}/.claude/cc-viewer/credentials.json)`, `Edit(${home}/.claude/cc-viewer/credentials.json)`, `Write(${home}/.claude/cc-viewer/credentials.json)`,
+        `Read(${home}/.claude/cc-viewer/master.key)`, `Edit(${home}/.claude/cc-viewer/master.key)`, `Write(${home}/.claude/cc-viewer/master.key)`,
+        // Backup copies of the vault (cc-viewer-config-backups/<ts>/) hold the same decryption
+        // kit (credentials.json + master.key) — deny the whole subtree or an IM worker could read
+        // a rolled backup and decrypt every secret.
+        `Read(${home}/.claude/cc-viewer-config-backups/**)`, `Edit(${home}/.claude/cc-viewer-config-backups/**)`, `Write(${home}/.claude/cc-viewer-config-backups/**)`,
       ],
     };
   }