cc-viewer 1.9.0 → 1.9.2

package/server/interceptor.js

@@ -22,6 +22,8 @@ import { sanitizePathComponent } from './lib/v2/layout.js';
 import { parseAgentId, findHeader } from './lib/v2/agent-id.js';
 import { parseUserId } from './lib/session-id.js';
 import { setRetryConfigPath, loadRetryConfig, DEFAULT_RETRY_CONFIG } from './lib/proxy/proxy-retry.js';
+import { writeJsonAtomic, mutateJsonSync } from './lib/json-store.js';
+import { readSecretOr, writeSecret, removeSecret } from './lib/credential-access.js';
 import { setProjectName } from './lib/project-state.js';
 import { consumePendingForResume, writeSnapshot, projectKeyForCwd } from './lib/system-prompt-snapshots.js';
 import { liveSystemPromptEnabled, getLaunchSystemPromptInfo, getLiveEntry, putLiveEntry, selectEntriesForModel, applyLiveSystem, knownInjectedTexts } from './lib/system-prompt-live.js';
@@ -186,16 +188,72 @@ function _writeWorkspaceActive(activeId, roles) {
   }
 }
 
+// Resolve a profile's effective apiKey for request injection. The key lives in the credential
+// vault (kind=profile-apiKey, ref=profile.id); a plaintext apiKey still present in profile.json
+// is the one-version read-fallback (pre-migration). FAIL-CLOSED: a profile with a baseURL whose
+// key cannot be decrypted (lost master.key / tampered ciphertext) must be excluded from routing —
+// otherwise proxy.js would forward the request to the third-party baseURL while the auth rewrite
+// is skipped, transmitting the user's default Anthropic credential to that host.
+function _resolveProfileApiKey(profile) {
+  if (!profile || profile.id === 'max') return { apiKey: '', unusable: false, reason: '' };
+  const legacyPlain = typeof profile.apiKey === 'string' ? profile.apiKey : '';
+  const { value, unreadable } = readSecretOr('profile-apiKey', profile.id, legacyPlain);
+  if (unreadable) return { apiKey: '', unusable: true, reason: 'unreadable' };
+  // FAIL-CLOSED: a profile that rewrites the URL to a third-party baseURL but resolves to NO key
+  // (no vault entry, no legacy plaintext) must also be excluded from routing. The URL rewrite runs
+  // unconditionally while the auth rewrite is guarded by `if (_effProfile.apiKey && ...)` — with an
+  // empty key the request would reach the third-party host carrying the user's own Anthropic
+  // credential (the exact outcome the unreadable branch above exists to prevent).
+  if (typeof profile.baseURL === 'string' && profile.baseURL && !value) {
+    return { apiKey: '', unusable: true, reason: 'keyless-baseurl' };
+  }
+  return { apiKey: value, unusable: false, reason: '' };
+}
+
+/**
+ * Decrypt-backfill apiKeys onto a raw profile.json list for READERS that consume the file
+ * directly (e.g. GET /api/proxy-profiles) rather than the in-memory _profilesById. Profiles
+ * whose key is unreadable are returned with an EMPTY apiKey (the caller masks/serves as-is);
+ * routing itself is fail-closed via _loadProxyProfile, which DROPS such profiles.
+ */
+export function hydrateProfilesWithApiKeys(profiles) {
+  return (Array.isArray(profiles) ? profiles : []).map((p) => {
+    if (!p || typeof p.id !== 'string') return p;
+    const { apiKey } = _resolveProfileApiKey(p);
+    return { ...p, apiKey };
+  });
+}
+
+// Throttle the per-profile "key unusable" diagnostic to once per profile id per process —
+// _loadProxyProfile re-runs on every 1.5s watchFile tick and would otherwise spam the log.
+const _reportedUnusableProfiles = new Set();
+
 function _loadProxyProfile() {
   try {
     const data = JSON.parse(readFileSync(PROFILE_PATH, 'utf-8'));
-    _profilesById = new Map((Array.isArray(data.profiles) ? data.profiles : [])
-      .filter(p => p && typeof p.id === 'string').map(p => [p.id, p]));
+    const rawProfiles = (Array.isArray(data.profiles) ? data.profiles : []).filter(p => p && typeof p.id === 'string');
+    // Decrypt-backfill apiKeys; drop profiles whose key is unreadable (fail-closed).
+    const profiles = [];
+    for (const p of rawProfiles) {
+      const { apiKey, unusable, reason } = _resolveProfileApiKey(p);
+      if (unusable) {
+        if (!_reportedUnusableProfiles.has(p.id)) {
+          _reportedUnusableProfiles.add(p.id);
+          const why = reason === 'keyless-baseurl'
+            ? 'has a baseURL but no apiKey — refusing to forward your default credential to a third-party host'
+            : 'apiKey unreadable (lost master.key or tampered credentials.json)';
+          reportSwallowed('proxy-profile.key-unusable', new Error(`profile "${p.id}" dropped: ${why}`));
+        }
+        continue;
+      }
+      profiles.push({ ...p, apiKey });
+    }
+    _profilesById = new Map(profiles.map(p => [p.id, p]));
     // active 解析优先级：workspace override > profile.json.active (兼容老数据 / 全局回退) > null
     const ws = _readWorkspaceActive();
     _roleIds = ws.roles;
     const activeId = ws.activeId || data.active;
-    const active = data.profiles?.find(p => p.id === activeId);
+    const active = profiles.find(p => p.id === activeId);
     _activeProfile = (active && active.id !== 'max') ? active : null;
   } catch (err) {
     _activeProfile = null;
@@ -226,14 +284,18 @@ function setActiveProfileForWorkspace(activeId, roles) {
   if (activeId !== undefined) {
     const normalizedId = (activeId && typeof activeId === 'string') ? activeId : 'max';
     try {
-      const data = existsSync(PROFILE_PATH)
-        ? JSON.parse(readFileSync(PROFILE_PATH, 'utf-8'))
-        : { profiles: [{ id: 'max', name: 'Default' }] };
-      if (data.active !== normalizedId) {
-        data.active = normalizedId;
-        mkdirSync(dirname(PROFILE_PATH), { recursive: true });
-        writeFileSync(PROFILE_PATH, JSON.stringify(data, null, 2), { mode: 0o600 });
-      }
+      // Read-merge-write INSIDE the shared profile.json lock (mutateJsonSync), so this whole-file
+      // update mutexes with the startup credential-strip and proxyProfilesPost — an unlocked
+      // snapshot could otherwise resurrect a stripped apiKey field or drop a concurrent list edit.
+      mutateJsonSync(PROFILE_PATH, (data) => {
+        const base = (data && typeof data === 'object' && !Array.isArray(data))
+          ? data
+          : { profiles: [{ id: 'max', name: 'Default' }] };
+        if (base.active !== normalizedId) base.active = normalizedId;
+        return base;
+      }, { mode: 0o600, strictCorrupt: true, fallback: { profiles: [{ id: 'max', name: 'Default' }] } });
+      // strictCorrupt: profile.json corrupt 时抛错(下方 catch 兜住、跳过本次写),绝不用 fallback
+      // 的 {max}-only 覆盖掉磁盘上虽损坏但可能仍可人工恢复的全部 profile。
       result.profile = true;
     } catch { /* 双失败场景下 result 全 false，由调用方自行兜底 */ }
   }
@@ -504,23 +566,49 @@ export function markSessionStart(payload) {
       console.warn('[ccv session-start] resume signal without transcript_path — ignored');
       return;
     }
-    // Soft cross-project guard: a foreign project's claude that somehow
-    // carries our CCVIEWER_PORT must not re-bind THIS project's writer. Only
-    // enforced when both sides are known (workspace mode may leave
-    // _projectName empty until bound).
-    if (cwd && typeof cwd === 'string' && _projectName) {
+    // Cross-project guard (2026-10-06, relaxed for true-/resume): a foreign project's
+    // claude that somehow carries our CCVIEWER_PORT must not re-bind THIS project's
+    // writer — BUT a resume in a PARALLEL project this server also manages (a live ccv
+    // PTY whose cwd maps to that project) is legitimate and must re-bind keyed by THAT
+    // project. Resolve the target project; drop only when neither bound nor a known
+    // live ccv project. This is what lets /api/resume-session switch a parallel
+    // viewed project and still have its writer follow.
+    let resumeProject = null; // null = bound project (default)
+    if (cwd && typeof cwd === 'string') {
       const cwdProject = projectKeyForCwd(cwd);
-      if (cwdProject !== _projectName) {
-        console.warn(`[ccv session-start] resume signal from project "${cwdProject}" ignored (bound to "${_projectName}")`);
-        return;
+      if (_projectName && cwdProject === _projectName) {
+        resumeProject = null; // bound project — default key
+      } else {
+        // Synchronously resolvable? No — isLiveClaudeProject lives in pty-manager
+        // (L2), imported lazily below. Compute the candidate key here and let the
+        // async gate decide whether to arm the switch.
+        resumeProject = cwdProject || null;
       }
     }
     const transcriptUuid = basename(transcriptPath, '.jsonl');
     if (source === 'resume') {
-      _v2Writer.beginResumeSwitch({
-        transcriptUuid,
-        hookSid: (typeof sessionId === 'string' && sessionId) ? sessionId : null,
-      });
+      const armSwitch = () => {
+        _v2Writer.beginResumeSwitch({
+          transcriptUuid,
+          hookSid: (typeof sessionId === 'string' && sessionId) ? sessionId : null,
+          // Keyed by the resumed conversation's project (bound = undefined default).
+          project: resumeProject || undefined,
+        });
+      };
+      if (!resumeProject || (_projectName && resumeProject === _projectName)) {
+        armSwitch();
+      } else {
+        // Parallel project: only arm when it's a live ccv-managed claude PTY.
+        import('./pty-manager.js')
+          .then((pm) => {
+            if (pm && typeof pm.isLiveClaudeProject === 'function' && pm.isLiveClaudeProject(resumeProject)) {
+              armSwitch();
+            } else {
+              console.warn(`[ccv session-start] resume signal from unmanaged project "${resumeProject}" ignored`);
+            }
+          })
+          .catch((err) => reportSwallowed('session-start.resume-project-gate', err));
+      }
     }
     // System-prompt snapshot, Bind B (system-prompt-snapshots.js): a process-level
     // -c/-r launch queued a resumeExpected pending at spawn (pty-manager). The
@@ -620,13 +708,20 @@ export function initForWorkspace(projectPath, { forceNew = false } = {}) { // es
   const dir = join(LOG_DIR, projectName);
   try { mkdirSync(dir, { recursive: true }); } catch {}
 
+  // Capture the project being switched AWAY from BEFORE rebinding: a scoped
+  // resetSessions(below) drops only THAT project's cached session bindings, so a
+  // concurrently-running BACKGROUND project (a cross-project /resume takeover's
+  // old project, still writing via entry._resumeProject) keeps its bindings and
+  // continues uninterrupted. Same-project re-init passes the same name (a no-op
+  // scoped clear of just that project, matching the old full clear for it).
+  const previousProject = _projectName;
   _projectName = projectName;
   setProjectName(projectName);
   _logDir = dir;
   // Fresh workspace context — no carried names apply; future requests must
   // create session dirs under the NEW project.
   _agentSpawnRegistry.clear();
-  _v2Writer.resetSessions(); // also clears the per-process `-c` adoption latch
+  _v2Writer.resetSessions(previousProject || null); // also clears the per-process `-c` adoption latch
   // A `--fork-session` / `-r` launch marks fork/resume intent; neither must
   // leak into a LATER workspace's `-c` (in a long-lived server that would
   // permanently suppress adoption). Clear both marks per launch and re-sync —
@@ -801,6 +896,9 @@ export function setupInterceptor() {
         if (isProxyTrace && options?.headers) {
           delete options.headers['x-cc-viewer-trace'];
         }
+        // NOTE: `x-ccv-project-dir` is stripped LATER (right before _originalFetch,
+        // after requestEntry has extracted `_resumeProject` from it) — stripping it
+        // here would delete it before the conversion copy below could read it.
 
         const timestamp = new Date().toISOString();
         let body = null;
@@ -864,10 +962,47 @@ export function setupInterceptor() {
             safeHeaders['authorization'] = '****';
           }
         }
+        // ccv-internal self-report headers (x-ccv-project-dir / x-ccv-instance) are routing
+        // metadata, not request content — drop them from the logged/forwarded `safeHeaders`
+        // copy so they never land in the on-disk journal or reach the frontend wire (they are
+        // extracted onto `_resumeProject`/`_ccvInstance` separately). Case-insensitive.
+        for (const k of Object.keys(safeHeaders)) {
+          const lk = k.toLowerCase();
+          if (lk === 'x-ccv-project-dir' || lk === 'x-ccv-instance') delete safeHeaders[k];
+        }
 
         requestEntry = {
           timestamp,
           project: (() => { try { return basename(process.cwd()); } catch { return 'unknown'; } })(),
+          // /resume global sessions: a child claude spawned for resume carries
+          // `x-ccv-project-dir` = its own cwd, so its traffic is logged under THAT
+          // project rather than this ccv process's cwd. Set ONLY the dedicated
+          // `_resumeProject` override (the writer prefers it over the bound
+          // project); `entry.project` keeps its original process-cwd meaning for
+          // every other consumer. projectKeyForCwd takes only the basename and
+          // sanitizes it, so the header cannot path-traverse.
+          ...(() => {
+            const dir = findHeader(headers, 'x-ccv-project-dir');
+            const proj = (typeof dir === 'string' && dir) ? projectKeyForCwd(dir) : '';
+            if (!proj) return {};
+            // Same-name session isolation (2026-10-07): also surface the RAW full cwd
+            // (`dir`, the findHeader output — NOT the projectKeyForCwd basename above)
+            // as `_resumeProjectCwd`, so the writer can stamp `meta.cwd` on the session
+            // dir. The read-side fallback then tightens by full-path cwd, telling two
+            // cross-dir same-basename projects apart (basename routing cannot). Using the
+            // basename here would never equal the read side's full-path targetCwd.
+            return { _resumeProject: proj, _resumeProjectCwd: dir };
+          })(),
+          // Multi-instance (2026-10-06): the spawned claude also self-reports its PTY
+          // instanceKey via `x-ccv-instance` (spawnClaude injects it). Surface it as
+          // `_ccvInstance` so the writer can pin the resolved sessionId to THIS exact process
+          // — basename routing cannot tell two same-cwd instances apart. Validated to the
+          // minted `ccv-<hex>` shape before use (it becomes a Map key downstream).
+          ...(() => {
+            const inst = findHeader(headers, 'x-ccv-instance');
+            const key = (typeof inst === 'string' && /^ccv-[0-9a-f]+$/.test(inst)) ? inst : '';
+            return key ? { _ccvInstance: key } : {};
+          })(),
           url: urlStr,
           method: options?.method || 'GET',
           headers: safeHeaders,
@@ -1169,6 +1304,32 @@ export function setupInterceptor() {
       catch (err) { reportSwallowed('interceptor.ingest-request', err); }
     }
 
+    // Strip the ccv-internal project self-report header right before forwarding
+    // upstream — AFTER requestEntry already read `_resumeProject` from it. Strip
+    // case-insensitively (the claude client applies it via ANTHROPIC_CUSTOM_HEADERS,
+    // so casing is not under ccv's control). `_fetchOpts` starts as the same object
+    // as `options` and is only shallow-copied on rewrite, so scrub BOTH.
+    // `x-ccv-instance` (the multi-instance self-report) is stripped the same way —
+    // it must never reach Anthropic.
+    const CCV_INTERNAL_HEADERS = ['x-ccv-project-dir', 'x-ccv-instance'];
+    const scrubHeaderBag = (hdrs) => {
+      if (!hdrs) return;
+      if (hdrs instanceof Headers) {
+        for (const name of CCV_INTERNAL_HEADERS) { if (hdrs.has(name)) hdrs.delete(name); }
+      } else if (typeof hdrs === 'object') {
+        for (const k of Object.keys(hdrs)) {
+          if (CCV_INTERNAL_HEADERS.includes(k.toLowerCase())) delete hdrs[k];
+        }
+      }
+    };
+    for (const optsBag of [options, _fetchOpts]) {
+      scrubHeaderBag(optsBag && optsBag.headers);
+    }
+    // Request-object form: `fetch(new Request(...))` carries headers on the Request itself
+    // (options may be undefined), so scrub those too or the internal header reaches upstream.
+    if (typeof Request !== 'undefined' && _fetchUrl instanceof Request) scrubHeaderBag(_fetchUrl.headers);
+    if (typeof Request !== 'undefined' && url instanceof Request && url !== _fetchUrl) scrubHeaderBag(url.headers);
+
     let response;
     try {
       response = await _originalFetch.call(this, _fetchUrl, _fetchOpts);
@@ -1229,6 +1390,10 @@ export function setupInterceptor() {
               url: requestEntry.url,
               response: { body: snap },
               body: { model: requestEntry.body?.model },
+              // B3 (multi-session view-attach): tag the live overlay stream with the
+              // session uuid so an attached client can show only ITS sid's typewriter
+              // and drop the other session's. Additive — older clients ignore it.
+              sessionId: parseUserId(requestEntry.body?.metadata?.user_id)?.sessionId ?? null,
             };
             sendStreamChunk(chunkEntry, ++liveChunkSeq, (ok) => {
               // 413 → 禁用当次流式，后续全由最终 v2 completion 交付
@@ -1252,6 +1417,9 @@ export function setupInterceptor() {
               url: requestEntry.url,
               response: { body: null },
               body: { model: requestEntry.body?.model },
+              // B3: same sessionId tag on the skeleton (seq 0) so the overlay filter
+              // keys on (timestamp, sessionId) from the very first frame.
+              sessionId: parseUserId(requestEntry.body?.metadata?.user_id)?.sessionId ?? null,
             }, 0, (ok) => { if (!ok) liveStreamEnabled = false; });
           }
 

package/server/lib/ask/ask-store.js

@@ -13,7 +13,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from '
 import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { renameSyncWithRetry } from '../file-api.js';
-import { withFileLockAsync } from '../async-file-lock.js';
+import { withJsonLock } from '../json-store.js';
 import { LOG_DIR } from '../../../findcc.js';
 
 const SCHEMA_VERSION = 1;
@@ -23,10 +23,14 @@ const SCHEMA_VERSION = 1;
 let _loggedPersistError = false;
 
 function getStoreFile() { return join(LOG_DIR, 'ask-store.json'); }
-function getLockFile() { return join(LOG_DIR, 'ask-store.lock'); }
 
+// Serialize every read-modify-write through the unified json-store kernel's async lock
+// (derived from the file name → ask-store.json.lock). The domain read/save (schema filter,
+// version wrap, entry cleaning) stays below in loadAskStore/saveAskStore; the kernel only
+// supplies the mutex via withJsonLock (lock-only, no read/write) because the store's on-disk
+// shape ({version,entries}) differs from its in-memory shape (plain entries map).
 function withLock(fn) {
-  return withFileLockAsync(getLockFile(), fn, { ensureDir: LOG_DIR });
+  return withJsonLock(getStoreFile(), fn, { ensureDir: LOG_DIR });
 }
 
 /**

package/server/lib/async-file-lock.js

@@ -8,6 +8,17 @@ import { mkdirSync } from 'node:fs';
 // 同进程内的 Promise 互斥锁（按 lockPath 分组）
 const _inProcessLocks = new Map();
 
+// Disk lock files this process currently holds via the async path (between _acquireFileLock
+// success and the matching unlink). Consulted by the SYNC lock flavor in json-store.js so it
+// never mistakes a live async holder (which yields the JS thread at every await inside its
+// critical section) for a stale own-pid lock and steals it.
+const _heldDiskLocks = new Set();
+
+/** True when this process currently holds `lockPath`'s disk lock via the async flavor. */
+export function hasLiveDiskHolder(lockPath) {
+  return _heldDiskLocks.has(lockPath);
+}
+
 function isPidAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
   try {
@@ -56,11 +67,23 @@ async function _acquireFileLock(lockPath, opts) {
   while (true) {
     try {
       const fh = await open(lockPath, 'wx');
-      if (writePid) {
-        await fh.writeFile(JSON.stringify({ pid: process.pid, ts: Date.now() }));
+      // Register the hold IMMEDIATELY on acquisition, before the pid-write await. A SYNC caller
+      // (json-store._acquireLockSync) that runs at that await boundary would otherwise see the lock
+      // file with our own pid but hasLiveDiskHolder===false, judge it a stale crash-leftover, steal
+      // and unlink it — clobbering this async holder's critical section (the exact lost update the
+      // sync flavor's reentrancy guard exists to prevent).
+      _heldDiskLocks.add(lockPath);
+      try {
+        if (writePid) {
+          await fh.writeFile(JSON.stringify({ pid: process.pid, ts: Date.now() }));
+        }
+        await fh.close();
+        return;
+      } catch (err) {
+        _heldDiskLocks.delete(lockPath); // never fully acquired → drop the registration
+        try { await fh.close(); } catch {}
+        throw err;
       }
-      await fh.close();
-      return;
     } catch (err) {
       if (err?.code === 'EEXIST') {
         if (Date.now() < deadline) {
@@ -108,10 +131,11 @@ export async function withFileLockAsync(lockPath, fn, opts = {}) {
   await prev;
 
   try {
-    await _acquireFileLock(lockPath, opts);
+    await _acquireFileLock(lockPath, opts); // registers in _heldDiskLocks at the acquisition point
     try {
       return await fn();
     } finally {
+      _heldDiskLocks.delete(lockPath);
       try { await unlink(lockPath); } catch {}
     }
   } finally {

package/server/lib/auth.js

@@ -9,9 +9,10 @@
 // unit-tested directly (loopback HTTP tests always look local, so they cannot
 // exercise the remote branch — `decideAuth` covers it as a pure function).
 import { randomBytes } from 'node:crypto';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, unlinkSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { renameSyncWithRetry } from './file-api.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { mutateJsonSync } from './json-store.js';
+import { readSecretOr, writeSecret, removeSecret } from './credential-access.js';
 import { LOG_DIR } from '../../findcc.js';
 import { tFor, localeFromAcceptLanguage } from '../i18n.js';
 
@@ -79,9 +80,14 @@ function normalizeAuth(cfg) {
 }
 
 // The password is kept in memory & over the admin API as plaintext (admin must be able
-// to view/copy it), but is base64-encoded on disk so preferences.json never shows the
-// raw password. This is light obfuscation, NOT real security — base64 is trivially
-// reversible; it only avoids the password sitting in literal plaintext in the file.
+// to view/copy it). On disk it lives in the encrypted credential vault (credentials.json)
+// as AES-256-GCM ciphertext — NOT in preferences.json. The legacy encoding was base64 inside
+// preferences.json (obfuscation only); those fields are migrated out at startup and cleared.
+//
+// CRITICAL fail-closed rule: a password that exists but cannot be decrypted (lost master.key,
+// tampered ciphertext) is "unreadable", NOT "empty". decideAuth treats an EMPTY password as
+// allow-all, so collapsing an unreadable secret to '' would open the LAN gate. We therefore
+// thread a `passwordUnreadable` flag through and deny on it before the empty-password branch.
 function encodePassword(plain) {
   return plain ? Buffer.from(plain, 'utf-8').toString('base64') : '';
 }
@@ -91,18 +97,32 @@ function decodePassword(stored) {
 }
 
 // ─── Scoped persistence (global default + optional per-project override) ───
-// preferences.json:
-//   auth:          { enabled, password(b64) }                  ← global default
-//   authByProject: { "<projectDir>": { enabled, password(b64) } }  ← optional overrides
+// preferences.json (after migration):
+//   auth:          { enabled }                  ← global default (password in vault)
+//   authByProject: { "<projectDir>": { enabled } }  ← optional overrides (password in vault)
+// Vault refs: 'lan-password:global' and 'lan-password:proj:<resolvedDir>'.
 // A project "has an override" iff a key exists for it (even if disabled). The gate
 // resolves: project override (if the key exists) else global. To inherit global again,
 // the override must be REMOVED (clearProjectOverride), not merely disabled.
 
-function decodeStored(a) {
-  return { enabled: !!(a && a.enabled), password: decodePassword(a && a.password) };
+// Vault ref for the LAN password of a scope. 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 (the writer and reader would use different keys).
+export function refFor(projectDir) {
+  return projectDir ? `proj:${resolve(projectDir)}` : 'global';
 }
-function encodeForDisk(normalized) {
-  return { enabled: normalized.enabled, password: encodePassword(normalized.password) };
+
+function decodeStored(a, projectDir = null) {
+  // No auth entry at all → the default "disabled, no password" shape; do NOT consult the vault
+  // (a stray vault entry must not resurrect a password for a scope the prefs say nothing about,
+  // e.g. after preferences.json was wiped/corrupt while credentials.json survived).
+  if (!a || typeof a !== 'object') return { enabled: false, password: '', passwordUnreadable: false };
+  const enabled = !!a.enabled;
+  // Legacy on-disk value (base64) is the read-fallback for the one-version transition window;
+  // the vault is authoritative when it holds the entry.
+  const legacyPlain = decodePassword(a.password);
+  const { value, unreadable } = readSecretOr('lan-password', refFor(projectDir), legacyPlain);
+  return { enabled, password: value, passwordUnreadable: unreadable };
 }
 
 /** Does this project have its own auth override? (key present, regardless of enabled) */
@@ -117,8 +137,9 @@ function hasOverride(prefs, projectDir) {
  */
 export function loadAuthConfig(projectDir = null) {
   const prefs = readPrefs();
-  const src = hasOverride(prefs, projectDir) ? prefs.authByProject[projectDir] : prefs.auth;
-  return decodeStored(src);
+  const overridden = hasOverride(prefs, projectDir);
+  const src = overridden ? prefs.authByProject[projectDir] : prefs.auth;
+  return decodeStored(src, overridden ? projectDir : null);
 }
 
 /**
@@ -130,38 +151,14 @@ export function loadAuthState(projectDir = null) {
   const prefs = readPrefs();
   const overridden = hasOverride(prefs, projectDir);
   return {
-    effective: decodeStored(overridden ? prefs.authByProject[projectDir] : prefs.auth),
-    global: decodeStored(prefs.auth),
+    effective: decodeStored(overridden ? prefs.authByProject[projectDir] : prefs.auth, overridden ? projectDir : null),
+    global: decodeStored(prefs.auth, null),
     scope: overridden ? 'project' : 'global',
     hasProjectOverride: overridden,
     projectDir: projectDir || null,
   };
 }
 
-function writePrefs(prefs) {
-  const p = getPrefsPath();
-  const dir = dirname(p);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
-  // Atomic tmp→rename so a crash mid-write can't truncate the password-bearing file
-  // (preferences.json also holds UI prefs + per-project forks). Mirrors prefs-store.js.
-  // TODO(prefs-lock): this path does NOT take the prefs-store lock (writePrefs is sync, its
-  // callers are sync) — auth writes are rare/admin-initiated, so the residual lost-update
-  // window vs a concurrent locked prefs write is accepted; atomicity rules out corruption.
-  // Dormant only while every mutatePrefs mutator stays synchronous (no await between its
-  // locked read and write); route auth writes through prefs-store.mutatePrefs if that changes.
-  const tmp = `${p}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`;
-  try {
-    writeFileSync(tmp, JSON.stringify(prefs, null, 2), { mode: 0o600 });
-    renameSyncWithRetry(tmp, p);
-    // writeFileSync's mode only applies on creation; a pre-existing file keeps its old
-    // perms. Re-assert 0600 — preferences.json now carries the (base64) password.
-    try { chmodSync(p, 0o600); } catch { /* best-effort; non-POSIX or race */ }
-  } catch (err) {
-    try { unlinkSync(tmp); } catch {}
-    throw err;
-  }
-}
-
 /**
  * Persist auth config (read-merge-write, preserving all other prefs). `opts.scope`
  * 'global' → the `auth` key; 'project' → authByProject[opts.projectDir] (requires
@@ -170,26 +167,37 @@ function writePrefs(prefs) {
  */
 export function saveAuthConfig(cfg, opts = {}) {
   const normalized = normalizeAuth(cfg);
-  const prefs = readPrefs();
   const scope = opts.scope === 'project' && opts.projectDir ? 'project' : 'global';
-  if (scope === 'project') {
-    if (!prefs.authByProject || typeof prefs.authByProject !== 'object') prefs.authByProject = {};
-    prefs.authByProject[opts.projectDir] = encodeForDisk(normalized);
-  } else {
-    prefs.auth = encodeForDisk(normalized);
-  }
-  writePrefs(prefs);
+  const projectDir = scope === 'project' ? opts.projectDir : null;
+  // Write the password to the vault FIRST. Only on success do we persist { enabled } (sans
+  // password) to preferences.json — otherwise the legacy field must be preserved so the secret
+  // is not lost. (writeSecret verifies the key is usable and reports+false on failure.)
+  const wrote = writeSecret('lan-password', refFor(projectDir), normalized.password);
+  // Read-merge-write INSIDE the kernel's sync lock so a concurrent prefs/IM save can't be
+  // lost between our read and write.
+  mutateJsonSync(getPrefsPath(), (prefs) => {
+    // persisted shape: { enabled } plus the legacy base64 password ONLY when the vault write
+    // failed (preserves the secret for a later migration) — removed once vault-backed.
+    const legacyField = wrote ? {} : { password: encodePassword(normalized.password) };
+    if (scope === 'project') {
+      if (!prefs.authByProject || typeof prefs.authByProject !== 'object') prefs.authByProject = {};
+      prefs.authByProject[opts.projectDir] = { enabled: normalized.enabled, ...legacyField };
+    } else {
+      prefs.auth = { enabled: normalized.enabled, ...legacyField };
+    }
+  }, { mode: 0o600 });
   return normalized;
 }
 
 /** Remove a project's override so it inherits the global default again. No-op if absent. */
 export function clearProjectOverride(projectDir) {
   if (!projectDir) return;
-  const prefs = readPrefs();
-  if (prefs.authByProject && Object.prototype.hasOwnProperty.call(prefs.authByProject, projectDir)) {
-    delete prefs.authByProject[projectDir];
-    writePrefs(prefs);
-  }
+  removeSecret('lan-password', refFor(projectDir));
+  mutateJsonSync(getPrefsPath(), (prefs) => {
+    if (prefs.authByProject && Object.prototype.hasOwnProperty.call(prefs.authByProject, projectDir)) {
+      delete prefs.authByProject[projectDir];
+    }
+  }, { mode: 0o600 });
 }
 
 /**
@@ -236,6 +244,7 @@ export function decideAuth(ctx) {
     isStaticAsset, pathname, isLocal,
     urlToken, cookieToken, accessToken,
     enabled, password, wantsHtml,
+    passwordUnreadable = false,
   } = ctx;
 
   // Admin = the credential-bearing / trusted-peer allow branches. Deliberately EXCLUDES the
@@ -246,6 +255,14 @@ export function decideAuth(ctx) {
     urlToken === accessToken ||
     cookieToken === accessToken;
 
+  // Fail-closed: a password that EXISTS but could not be decrypted (lost master.key / tampered
+  // ciphertext) must deny BEFORE the empty-password allow branch below — otherwise an unreadable
+  // secret collapses to '' and opens the LAN gate. Login page stays reachable so the admin can
+  // still authenticate via token (which does not depend on the vault).
+  if (passwordUnreadable && !isAdmin) {
+    return { action: wantsHtml ? 'login-page' : 'unauthorized', isAdmin };
+  }
+
   if (
     isStaticAsset ||
     pathname === '/api/auth/login' || // login endpoint must be reachable unauthenticated