cc-viewer 1.8.19 → 1.8.21

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

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;
+}