@lifeaitools/clauth 1.6.0 → 1.7.2

package/cli/commands/serve.js

@@ -21,6 +21,13 @@ import { appendFile, readdir, readFile, writeFile, rm, mkdir, stat, rename, cp }
 import fg from "fast-glob";
 import { rgPath } from "@vscode/ripgrep";
 import { createStudioDebugRuntime } from "../studio-debug.js";
+import { writeCredentialWithRecovery } from "../recovery.js";
+import * as fsGit from "../lib/fs-git.js";
+import {
+  getWatchdogStatuses,
+  readWatchdogEvents,
+  restartWatchdogService,
+} from "../watchdog-registry.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "../../package.json"), "utf8"));
@@ -309,9 +316,14 @@ function createRotationEngine(password, machineHash, logFile) {
       const result = await config.rotate(currentKey);
       if (!result.newKey) throw new Error("Rotation returned no new key");
 
-      // Write new key to vault
-      const { token: wt, timestamp: wts } = deriveToken(password, machineHash);
-      const writeResult = await api.write(password, machineHash, wt, wts, serviceName, result.newKey);
+      // Write new key to vault after preserving an encrypted recovery snapshot.
+      const { result: writeResult } = await writeCredentialWithRecovery({
+        password,
+        machineHash,
+        service: serviceName,
+        value: result.newKey,
+        logFile,
+      });
       if (writeResult.error) throw new Error(`Write failed: ${writeResult.error}`);
 
       // Update expiry in state
@@ -412,6 +424,26 @@ const STAGED_PID_FILE = path.join(os.tmpdir(), "clauth-serve-staged.pid");
 const LOG_FILE = path.join(os.tmpdir(), "clauth-serve.log");
 const LIVE_PORT = 52437;
 const STAGED_PORT = 52438;
+const WRITE_TOKEN_BYTES = 32;
+const WRITE_TOKEN_TTL_MS = 10 * 60 * 1000;
+
+function makeWriteToken() {
+  return {
+    token: crypto.randomBytes(WRITE_TOKEN_BYTES).toString("base64url"),
+    expiresAt: Date.now() + WRITE_TOKEN_TTL_MS,
+  };
+}
+
+function validateWriteToken(req, writeSession) {
+  if (!writeSession?.token || Date.now() > writeSession.expiresAt) return false;
+  const header = req.headers["x-clauth-write-token"] || req.headers.authorization;
+  const token = Array.isArray(header) ? header[0] : header;
+  if (!token) return false;
+  const supplied = String(token).startsWith("Bearer ") ? String(token).slice(7) : String(token);
+  const a = Buffer.from(supplied);
+  const b = Buffer.from(writeSession.token);
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
 
 // ── PID helpers ──────────────────────────────────────────────
 function readPid() {
@@ -752,6 +784,7 @@ function dashboardHtml(port, whitelist, isStaged = false) {
     <button class="btn-add" onclick="toggleAddService()">+ Add Service</button>
     <button class="btn-check" id="check-btn" onclick="checkAll()">⬤ Check All</button>
     <button class="btn-ccandme" id="ccandme-btn" onclick="launchCCandMe()" title="Launch CCandMe — 4-pane WezTerm: Claude + Codex + Me">⚡ CCandMe</button>
+    <button class="btn-lock" id="unlock-writes-btn" onclick="unlockWrites()" title="Enter password to enable saving changes this browser session (needed after a daemon restart when auto-unlocked via --pw)">🔓 Unlock Writes</button>
     <button class="btn-lock" onclick="lockVault()">🔒 Lock</button>
     <button class="btn-stop" onclick="restartDaemon()" style="background:#1a2e1a;border:1px solid #166534;color:#86efac" title="Restart daemon — keeps vault unlocked">↺ Restart</button>
     <button class="btn-stop" onclick="stopDaemon()" style="background:#7f1d1d;border:1px solid #991b1b;color:#fca5a5" title="Stop daemon — password required on next start">⏹ Stop</button>
@@ -968,6 +1001,13 @@ function renderSetPanel(name) {
 }
 
 // ── Boot: check lock state ──────────────────
+let writeToken = null;
+
+function writeHeaders(extra) {
+  if (!writeToken) throw new Error("Write access requires password unlock in this browser session.");
+  return { ...(extra || {}), "X-Clauth-Write-Token": writeToken };
+}
+
 async function boot() {
   try {
     const ping = await fetch(BASE + "/ping").then(r => r.json());
@@ -1051,6 +1091,7 @@ function showMain(ping) {
   }
   pollTunnel();
   updateBuildStatus();
+  refreshWriteLockUi();
 }
 
 // ── Unlock ──────────────────────────────────
@@ -1090,6 +1131,7 @@ async function unlock() {
       throw new Error(r.error + rem);
     }
 
+    writeToken = r.write_token || null;
     input.value = "";
     const ping = await fetch(BASE + "/ping").then(r => r.json());
     showMain(ping);
@@ -1107,9 +1149,38 @@ async function unlock() {
 // ── Lock ────────────────────────────────────
 async function lockVault() {
   const r = await fetch(BASE + "/lock", { method: "POST" }).then(r => r.json()).catch(() => ({}));
+  writeToken = null;
   showLockScreen(r.hard_locked || false);
 }
 
+// ── Unlock writes (re-establish write scope without locking) ──
+// Needed when the daemon auto-unlocks via --pw/boot.key: the page never sees the
+// unlock screen, so it holds no write token. POST /auth mints one (10-min TTL).
+async function unlockWrites() {
+  if (writeToken && !confirm("Writes are already unlocked this session. Re-unlock?")) return;
+  const pw = prompt("Enter your vault password to enable saving changes (10-minute write session):");
+  if (!pw) return;
+  try {
+    const r = await fetch(BASE + "/auth", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ password: pw }),
+    }).then(r => r.json());
+    if (r.error) { alert("Unlock failed: " + r.error); return; }
+    writeToken = r.write_token || null;
+    refreshWriteLockUi();
+    alert(writeToken ? "Writes unlocked for 10 minutes." : "Unlock did not return a write token.");
+  } catch (e) { alert("Unlock error: " + (e.message || e)); }
+}
+
+// Reflect write-lock state on the button so it is obvious when a save will fail.
+function refreshWriteLockUi() {
+  const b = document.getElementById("unlock-writes-btn");
+  if (!b) return;
+  if (writeToken) { b.textContent = "🔓 Writes On"; b.style.opacity = "0.6"; b.style.borderColor = ""; }
+  else { b.textContent = "🔓 Unlock Writes"; b.style.opacity = "1"; b.style.borderColor = "#f59e0b"; }
+}
+
 // ── Make Live (blue-green: promote staged instance to live port) ──
 async function makeLive() {
   if (!confirm("Promote this staged instance to live?\\n\\nThe current live daemon (port ${LIVE_PORT}) will be stopped and this instance will restart on port ${LIVE_PORT}.")) return;
@@ -1398,7 +1469,7 @@ async function rotateKey(name) {
   const rotBtn = document.getElementById("rotbtn-" + name);
   if (rotBtn) { rotBtn.disabled = true; rotBtn.textContent = "rotating…"; }
   try {
-    const r = await fetch(BASE + "/rotate/" + name, { method: "POST" }).then(r => r.json());
+    const r = await fetch(BASE + "/rotate/" + name, { method: "POST", headers: writeHeaders() }).then(r => r.json());
     if (r.ok) {
       if (rotBtn) { rotBtn.textContent = "✓ rotated"; rotBtn.style.background = "#166534"; }
       loadExpiry(); // refresh badges
@@ -1419,7 +1490,7 @@ async function setExpiry(name) {
   try {
     await fetch(BASE + "/set-expiry/" + name, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: writeHeaders({ "Content-Type": "application/json" }),
       body: JSON.stringify({ expires_at: expiresAt, rotation_days: parseInt(days) }),
     });
     loadExpiry();
@@ -1487,7 +1558,7 @@ async function saveProject(name) {
   try {
     const r = await fetch(BASE + "/update-service", {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: writeHeaders({ "Content-Type": "application/json" }),
       body: JSON.stringify({ service: name, project: project || "" })
     }).then(r => r.json());
     if (r.locked) { showLockScreen(); return; }
@@ -1532,7 +1603,7 @@ async function saveLabel(name) {
   try {
     const r = await fetch(BASE + "/update-service", {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: writeHeaders({ "Content-Type": "application/json" }),
       body: JSON.stringify({ service: name, label: newLabel })
     }).then(r => r.json());
     if (r.locked) { showLockScreen(false); return; }
@@ -1556,7 +1627,7 @@ async function saveRename(oldName) { await saveLabel(oldName); }
 async function deleteService(name) {
   if (!confirm(\`Delete service "\${name}"? This cannot be undone.\`)) return;
   try {
-    const r = await fetch(BASE + "/delete/" + name, { method: "POST" }).then(r => r.json());
+    const r = await fetch(BASE + "/delete/" + name, { method: "POST", headers: writeHeaders() }).then(r => r.json());
     if (r.locked) { showLockScreen(false); return; }
     if (r.error) throw new Error(r.error);
     loadServices();
@@ -1612,15 +1683,15 @@ async function saveKey(name) {
     value = JSON.stringify(obj);
   } else {
     const input = document.getElementById("set-input-" + name);
-    value = input ? input.value.trim() : "";
-    if (!value) { msg.className = "set-msg fail"; msg.textContent = "Value is empty."; return; }
+    value = input ? input.value : "";
+    if (!value.trim()) { msg.className = "set-msg fail"; msg.textContent = "Value is empty."; return; }
   }
 
   msg.className = "set-msg"; msg.textContent = "Saving…";
   try {
     const r = await fetch(BASE + "/set/" + name, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: writeHeaders({ "Content-Type": "application/json" }),
       body: JSON.stringify({ value })
     }).then(r => r.json());
 
@@ -1658,7 +1729,7 @@ async function toggleService(name) {
   try {
     const r = await fetch(BASE + "/toggle/" + name, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: writeHeaders({ "Content-Type": "application/json" }),
       body: JSON.stringify({ enabled: newState })
     }).then(r => r.json());
 
@@ -1763,12 +1834,13 @@ async function changePassword() {
   try {
     const r = await fetch(BASE + "/change-pw", {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: writeHeaders({ "Content-Type": "application/json" }),
       body: JSON.stringify({ newPassword: newPw })
     }).then(r => r.json());
 
     if (r.locked) { showLockScreen(); return; }
     if (r.error) throw new Error(r.error);
+    writeToken = r.write_token || null;
 
     msg.className = "chpw-msg ok"; msg.textContent = "✓ Password updated";
     document.getElementById("chpw-new").value = "";
@@ -1838,7 +1910,7 @@ async function addService() {
     if (project) payload.project = project;
     const r = await fetch(BASE + "/add-service", {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: writeHeaders({ "Content-Type": "application/json" }),
       body: JSON.stringify(payload)
     }).then(r => r.json());
 
@@ -2058,7 +2130,7 @@ async function wizSubmitCfToken() {
 
   const r = await fetch(BASE + "/tunnel/setup/cf-token", {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers: writeHeaders({ "Content-Type": "application/json" }),
     body: JSON.stringify({ token }),
   }).then(r => r.json()).catch(() => null);
 
@@ -2496,6 +2568,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
   const UNKNOWN_SERVICE_THRESHOLD = 2;    // misses before we return the full service list
   let authHardLocked = false;
   let password = initPassword || null;   // null = locked; set via POST /auth
+  let writeSession = null;               // null until explicit password auth grants write scope
   const machineHash = getMachineHash();
 
   // Rotation engine — starts after unlock
@@ -2522,6 +2595,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
       whitelist,
       failCount,
       MAX_FAILS,
+      writeEnabled: process.env.CLAUTH_MCP_WRITE === "1",
     };
   }
 
@@ -2916,6 +2990,22 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
     const studioDebugHandled = await studioDebugRuntime.handle(req, res, url, CORS);
     if (studioDebugHandled !== false) return;
 
+    if (method === "GET" && reqPath === "/watchdog/services") {
+      return ok(res, await getWatchdogStatuses());
+    }
+
+    if (method === "GET" && reqPath === "/watchdog/events") {
+      const limit = Number(url.searchParams.get("limit") || 100);
+      return ok(res, { events: readWatchdogEvents(limit) });
+    }
+
+    const restartMatch = reqPath.match(/^\/watchdog\/services\/([^/]+)\/restart$/);
+    if (method === "POST" && restartMatch) {
+      const result = restartWatchdogService(decodeURIComponent(restartMatch[1]));
+      res.writeHead(result.ok ? 200 : 403, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(result));
+    }
+
     // ── Hosts that bypass OAuth (fresh domains for claude.ai compatibility) ──
     const NOAUTH_HOSTS = ["fs.regendevcorp.com", "clauth.regendevcorp.com", "chitchat.regendevcorp.com"];
     const requestHost = (req.headers.host || "").split(":")[0].toLowerCase();
@@ -3115,12 +3205,13 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
     const MCP_PATHS = ["/mcp", "/gws", "/clauth", "/fs", "/chitchat", "/codevelop"];
     const isMcpPath = MCP_PATHS.includes(reqPath);
     function toolsForPath(p) {
-      if (p === "/gws")      return MCP_TOOLS.filter(t => t.name.startsWith("gws_"));
-      if (p === "/clauth")   return MCP_TOOLS.filter(t => t.name.startsWith("clauth_") || t.name === "monkey_dispatch" || t.name.startsWith("terminal_") || t.name.startsWith("channel_"));
-      if (p === "/fs")       return MCP_TOOLS.filter(t => t.name.startsWith("fs_"));
-      if (p === "/chitchat") return MCP_TOOLS.filter(t => t.name.startsWith("chitchat_"));
-      if (p === "/codevelop") return MCP_TOOLS.filter(t => t.name.startsWith("codevelop_"));
-      return MCP_TOOLS; // /mcp — all tools
+      const tools = filterMcpToolsForWriteMode(MCP_TOOLS);
+      if (p === "/gws")      return tools.filter(t => t.name.startsWith("gws_"));
+      if (p === "/clauth")   return tools.filter(t => t.name.startsWith("clauth_") || t.name === "monkey_dispatch" || t.name.startsWith("terminal_") || t.name.startsWith("channel_"));
+      if (p === "/fs")       return tools.filter(t => t.name.startsWith("fs_"));
+      if (p === "/chitchat") return tools.filter(t => t.name.startsWith("chitchat_"));
+      if (p === "/codevelop") return tools.filter(t => t.name.startsWith("codevelop_"));
+      return tools; // /mcp — all tools
     }
     function serverNameForPath(p) {
       if (p === "/gws")      return "gws";
@@ -3324,7 +3415,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
       if (rpcMethod === "tools/list") {
         sseSend(session.res, "message", {
           jsonrpc: "2.0", id,
-          result: { tools: MCP_TOOLS }
+          result: { tools: filterMcpToolsForWriteMode(MCP_TOOLS) }
         });
         return;
       }
@@ -4121,6 +4212,16 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
       return false;
     }
 
+    function writeGuard(req, res) {
+      if (lockedGuard(res)) return true;
+      if (!validateWriteToken(req, writeSession)) {
+        res.writeHead(403, { "Content-Type": "application/json", ...CORS });
+        res.end(JSON.stringify({ error: "write token required", write_locked: true }));
+        return true;
+      }
+      return false;
+    }
+
     // GET /meta — return valid key_types from DB check constraint
     if (method === "GET" && reqPath === "/meta") {
       if (lockedGuard(res)) return;
@@ -4311,6 +4412,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
         const result = await api.test(pw, machineHash, token, timestamp);
         if (result.error) throw new Error(result.error);
         password = pw;   // unlock — store in process memory only
+        writeSession = makeWriteToken();
         authFailCount = 0;
         authHardLocked = false;
         const logLine = `[${new Date().toISOString()}] Vault unlocked\n`;
@@ -4365,7 +4467,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
           tunnelStatus = "starting";
           startTunnel().catch(() => {});
         }
-        return ok(res, { ok: true, locked: false });
+        return ok(res, { ok: true, locked: false, write_token: writeSession.token, write_expires_at: new Date(writeSession.expiresAt).toISOString() });
       } catch {
         authFailCount++;
         const authRemaining = MAX_AUTH_FAILS - authFailCount;
@@ -4386,6 +4488,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
     // POST /lock — clear password from memory
     if (method === "POST" && reqPath === "/lock") {
       password = null;
+      writeSession = null;
       stopTunnel();
       const logLine = `[${new Date().toISOString()}] Vault locked\n`;
       try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
@@ -4395,7 +4498,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
     // POST /rename/:service — rename a service
     const renameMatch = reqPath.match(/^\/rename\/([a-zA-Z0-9_-]+)$/);
     if (method === "POST" && renameMatch) {
-      if (lockedGuard(res)) return;
+      if (writeGuard(req, res)) return;
       const service = renameMatch[1].toLowerCase();
       let body;
       try { body = await readBody(req); } catch {
@@ -4420,7 +4523,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
     // POST /delete/:service — remove a service entirely
     const deleteMatch = reqPath.match(/^\/delete\/([a-zA-Z0-9_-]+)$/);
     if (method === "POST" && deleteMatch) {
-      if (lockedGuard(res)) return;
+      if (writeGuard(req, res)) return;
       const service = deleteMatch[1].toLowerCase();
       try {
         const { token, timestamp } = deriveToken(password, machineHash);
@@ -4435,7 +4538,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
     // POST /toggle/:service — enable or disable a service
     const toggleMatch = reqPath.match(/^\/toggle\/([a-zA-Z0-9_-]+)$/);
     if (method === "POST" && toggleMatch) {
-      if (lockedGuard(res)) return;
+      if (writeGuard(req, res)) return;
       const service = toggleMatch[1].toLowerCase();
 
       let body;
@@ -4519,7 +4622,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
 
     // POST /rotate/:service — manually trigger rotation for a service
     if (method === "POST" && reqPath.startsWith("/rotate/")) {
-      if (lockedGuard(res)) return;
+      if (writeGuard(req, res)) return;
       const service = reqPath.slice("/rotate/".length);
       if (!service) {
         res.writeHead(400, { "Content-Type": "application/json", ...CORS });
@@ -4531,7 +4634,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
 
     // POST /set-expiry/:service — set expiry date for a service
     if (method === "POST" && reqPath.startsWith("/set-expiry/")) {
-      if (lockedGuard(res)) return;
+      if (writeGuard(req, res)) return;
       const service = reqPath.slice("/set-expiry/".length);
       let body;
       try { body = await readBody(req); } catch {
@@ -4688,7 +4791,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
 
     // POST /tunnel/setup/cf-token
     if (method === "POST" && reqPath === "/tunnel/setup/cf-token") {
-      if (lockedGuard(res)) return;
+      if (writeGuard(req, res)) return;
       let body;
       try { body = await readBody(req); } catch { return strike(res, 400, "Invalid JSON"); }
       const { token: cfToken } = body;
@@ -4708,9 +4811,8 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
         const accountId = ad?.result?.[0]?.id;
         const accountName = ad?.result?.[0]?.name;
 
-        // Save token to vault using api.write (same as /set/:service)
-        const { token: t, timestamp } = deriveToken(password, machineHash);
-        await api.write(password, machineHash, t, timestamp, "cloudflare", cfToken);
+        // Save token to vault using the same guarded recovery path as /set/:service.
+        await writeCredentialWithRecovery({ password, machineHash, service: "cloudflare", value: cfToken, logFile: LOG_FILE });
 
         // Save accountId to clauth_config
         const sbUrl = (api.getBaseUrl() || "").replace("/functions/v1/auth-vault", "");
@@ -4991,7 +5093,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
 
     // POST /change-pw — change master password (must be unlocked)
     if (method === "POST" && reqPath === "/change-pw") {
-      if (lockedGuard(res)) return;
+      if (writeGuard(req, res)) return;
 
       let body;
       try { body = await readBody(req); } catch {
@@ -5011,9 +5113,10 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
         const result = await api.changePassword(password, machineHash, token, timestamp, newSeedHash);
         if (result.error) throw new Error(result.error);
         password = newPassword;  // update in-memory password to new one
+        writeSession = makeWriteToken();
         const logLine = `[${new Date().toISOString()}] Password changed\n`;
         try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
-        return ok(res, { ok: true });
+        return ok(res, { ok: true, write_token: writeSession.token, write_expires_at: new Date(writeSession.expiresAt).toISOString() });
       } catch (err) {
         res.writeHead(502, { "Content-Type": "application/json", ...CORS });
         return res.end(JSON.stringify({ error: err.message }));
@@ -5023,7 +5126,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
     // POST /set/:service — write a new key value into vault
     const setMatch = reqPath.match(/^\/set\/([a-zA-Z0-9_-]+)$/);
     if (method === "POST" && setMatch) {
-      if (lockedGuard(res)) return;
+      if (writeGuard(req, res)) return;
       const service = setMatch[1].toLowerCase();
 
       if (whitelist && !whitelist.includes(service)) {
@@ -5042,10 +5145,9 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
       }
 
       try {
-        const { token, timestamp } = deriveToken(password, machineHash);
-        const result = await api.write(password, machineHash, token, timestamp, service, value.trim());
+        const { result, snapshot, normalized } = await writeCredentialWithRecovery({ password, machineHash, service, value, logFile: LOG_FILE });
         if (result.error) return strike(res, 502, result.error);
-        return ok(res, { ok: true, service });
+        return ok(res, { ok: true, service, recovery_snapshot: snapshot?.ok ? true : false, normalized });
       } catch (err) {
         return strike(res, 502, err.message);
       }
@@ -5053,7 +5155,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
 
     // POST /generate-token — generate a cryptographically random bearer token and store it
     if (method === "POST" && reqPath === "/generate-token") {
-      if (lockedGuard(res)) return;
+      if (writeGuard(req, res)) return;
 
       let body;
       try { body = await readBody(req); } catch {
@@ -5075,10 +5177,9 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
       try {
         const randomHex = crypto.randomBytes(32).toString("hex");
         const token = `${prefix}${randomHex}`;
-        const { token: authToken, timestamp } = deriveToken(password, machineHash);
-        const result = await api.write(password, machineHash, authToken, timestamp, service, token);
+        const { result, snapshot } = await writeCredentialWithRecovery({ password, machineHash, service, value: token, logFile: LOG_FILE, normalize: false });
         if (result.error) return strike(res, 502, result.error);
-        return ok(res, { token, service, stored: true });
+        return ok(res, { token, service, stored: true, recovery_snapshot: snapshot?.ok ? true : false });
       } catch (err) {
         return strike(res, 502, err.message);
       }
@@ -5086,7 +5187,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
 
     // POST /add-service — register a new service in the vault
     if (method === "POST" && reqPath === "/add-service") {
-      if (lockedGuard(res)) return;
+      if (writeGuard(req, res)) return;
 
       let body;
       try { body = await readBody(req); } catch {
@@ -5118,7 +5219,7 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
 
     // POST /update-service — update service metadata (project, label, description)
     if (method === "POST" && reqPath === "/update-service") {
-      if (lockedGuard(res)) return;
+      if (writeGuard(req, res)) return;
 
       let body;
       try { body = await readBody(req); } catch {
@@ -6316,7 +6417,7 @@ async function getFileserverMounts(vault) {
 async function resolveInMount(requestedPath, mountName, vault) {
   const { mounts, error } = await getFileserverMounts(vault);
   if (error) return { error };
-  if (!mounts || mounts.length === 0) return { error: "No fileserver services configured. Add one with key_type='fileserver' and value: {\"path\": \"C:/Dev/regen-root\", \"access\": \"rwd\"}" };
+  if (!mounts || mounts.length === 0) return { error: "No fileserver services configured. Add one with key_type='fileserver' and value: {\"path\": \"C:/Dev/regen-root\", \"access\": \"rwdg\"}  (access flags: r=read w=write d=delete g=git)" };
   const mount = mountName ? mounts.find(m => m.name === mountName) : mounts[0];
   if (!mount) return { error: `Mount '${mountName}' not found. Available: ${mounts.map(m => m.name).join(", ")}` };
   if (!mount.path) return { error: `Fileserver '${mount.name}' has no path configured` };
@@ -6411,6 +6512,15 @@ function runGitRaw(cwd, args, opts = {}) {
   return res.stdout || Buffer.alloc(0);
 }
 
+// Read a single credential value from the vault inside an MCP handler.
+// (The git operations themselves live in ../lib/fs-git.js — pure + testable.)
+async function vaultRetrieveValue(vault, service) {
+  if (!vault.password) return { error: "locked" };
+  if (vault.whitelist && !vault.whitelist.includes(service.toLowerCase())) return { error: "not_in_whitelist" };
+  const { token, timestamp } = deriveToken(vault.password, vault.machineHash);
+  return api.retrieve(vault.password, vault.machineHash, token, timestamp, service);
+}
+
 function normalizeRepoPath(p) {
   if (!p || typeof p !== "string") return null;
   const normalized = p.replace(/\\/g, "/").replace(/^\/+/, "");
@@ -7144,8 +7254,79 @@ const MCP_TOOLS = [
     description: "List configured filesystem mounts (fileserver services from vault).",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
   },
+  {
+    name: "fs_repo_status",
+    description: "Get the current git state of the mounted repo in ONE call: branch, HEAD sha + subject, whether the tree is clean or dirty (with changed paths), staged paths, how far ahead/behind the remote you are, and whether a merge or rebase is in progress. Call this first so you KNOW what you are working with before committing — you never have to guess whether your edits or a previous push landed. Requires 'g' (git) access on the mount.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_use_branch",
+    description: "Safely make sure you are on a branch before committing. Switches to an existing branch, or creates a new one from the current HEAD when create=true. Your uncommitted edits are carried forward; if switching would overwrite local changes it refuses and leaves the tree untouched, telling you which files block the switch. Refuses while a merge/rebase is in progress. Requires 'g' (git) access on the mount.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        branch: { type: "string", description: "Branch name to switch to (or create)" },
+        create: { type: "boolean", description: "Create a new branch from current HEAD instead of switching to an existing one (default false)" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      required: ["branch"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_commit",
+    description: "Commit and push to GitHub: stages changes, commits, and PUSHES by default — usually a single call is all you need after editing. Handles the messy cases: nothing-to-commit returns cleanly (no error); a merge/rebase in progress or a detached HEAD is refused with a clear message; if the branch is behind the remote it auto-rebases and retries the push, and on conflict it aborts the rebase (restoring your tree) and keeps the commit local so nothing is lost. Refuses to push protected branches (main/master/production) — those are promoted by a human. Returns the commit sha, the exact files committed, whether the push succeeded, and ahead/behind counts, so you never need a follow-up status call. Set dry_run=true first to preview what WOULD be committed/pushed without doing it. Set expected_head to refuse committing if the base moved under you. Push auth uses the vault github token directly (never exposed). Requires 'g' (git) access on the mount.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        message: { type: "string", description: "Commit message. Required for a real commit; optional when dry_run=true." },
+        paths: { type: "array", items: { type: "string" }, description: "Repo-relative paths to commit. Omit to commit ALL current changes in the repo." },
+        push: { type: "boolean", description: "Push to the remote after committing (default true)" },
+        dry_run: { type: "boolean", description: "Preview only: returns the branch, the files that would be committed, and whether/where it would push — without staging, committing, or pushing. Use to confirm before a real push." },
+        expected_head: { type: "string", description: "Optimistic-concurrency guard: the commit SHA you believe HEAD is on. If HEAD has moved, the commit is refused so you don't build on a stale base." },
+        remote: { type: "string", description: "Git remote name (default: origin)" },
+        author_name: { type: "string", description: "Commit author name (default: clauth-fs)" },
+        author_email: { type: "string", description: "Commit author email (default: fs@clauth.local)" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_diff",
+    description: "Show the unified diff of your changes so you can self-verify BEFORE committing/pushing — essential after large or multi-step edits. Default compares the working tree to the last commit (HEAD). Pass ref (e.g. 'origin/develop') to compare against a remote branch and catch staleness — i.e. see exactly how your working tree differs from what's on the remote, in one call. Pass staged=true to see only what's staged. Returns a --stat summary plus the patch (capped at 60KB; `truncated` flags when hit). Requires 'g' (git) access on the mount.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        paths: { type: "array", items: { type: "string" }, description: "Repo-relative paths to limit the diff to. Omit for all changes." },
+        ref: { type: "string", description: "Compare the working tree against this ref instead of HEAD (e.g. 'origin/develop', a tag, or a commit sha). Use for remote/staleness comparison." },
+        staged: { type: "boolean", description: "Show only staged changes (index vs HEAD) instead of the full working-tree diff." },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      additionalProperties: false,
+    },
+  },
 ];
 
+const MCP_WRITE_TOOL_NAMES = new Set([
+  "clauth_enable",
+  "clauth_disable",
+  "clauth_set_project",
+  "clauth_generate_token",
+]);
+
+function filterMcpToolsForWriteMode(tools) {
+  if (process.env.CLAUTH_MCP_WRITE === "1") return tools;
+  return tools.filter(tool => !MCP_WRITE_TOOL_NAMES.has(tool.name));
+}
+
 function writeTempSecret(service, value) {
   const filePath = path.join(os.tmpdir(), `.clauth-${service}`);
   fs.writeFileSync(filePath, value, { mode: 0o600 });
@@ -7176,6 +7357,11 @@ function mcpError(text) {
 const GWS_EXEC_OPTS = { encoding: "utf8", timeout: 30000, windowsHide: true, shell: os.platform() === "win32" ? "bash" : undefined };
 
 async function handleMcpTool(vault, name, args) {
+  const requireMcpWrite = () => {
+    if (vault.writeEnabled) return null;
+    return mcpError("MCP write tools are disabled by default. Launch clauth with CLAUTH_MCP_WRITE=1 for an explicit write-capable session.");
+  };
+
   switch (name) {
     case "clauth_ping": {
       return mcpResult(
@@ -7357,6 +7543,8 @@ async function handleMcpTool(vault, name, args) {
     }
 
     case "clauth_enable": {
+      const writeError = requireMcpWrite();
+      if (writeError) return writeError;
       if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
       const service = (args.service || "").toLowerCase();
       if (!service) return mcpError("service is required");
@@ -7371,6 +7559,8 @@ async function handleMcpTool(vault, name, args) {
     }
 
     case "clauth_disable": {
+      const writeError = requireMcpWrite();
+      if (writeError) return writeError;
       if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
       const service = (args.service || "").toLowerCase();
       if (!service) return mcpError("service is required");
@@ -7410,6 +7600,8 @@ async function handleMcpTool(vault, name, args) {
     }
 
     case "clauth_set_project": {
+      const writeError = requireMcpWrite();
+      if (writeError) return writeError;
       if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
       const service = (args.service || "").toLowerCase();
       const project = args.project;
@@ -7461,6 +7653,8 @@ async function handleMcpTool(vault, name, args) {
     }
 
     case "clauth_generate_token": {
+      const writeError = requireMcpWrite();
+      if (writeError) return writeError;
       if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
       const service = (args.service || "").trim().toLowerCase();
       const prefix = args.prefix || "";
@@ -7468,8 +7662,14 @@ async function handleMcpTool(vault, name, args) {
       try {
         const randomHex = crypto.randomBytes(32).toString("hex");
         const generatedToken = `${prefix}${randomHex}`;
-        const { token: authToken, timestamp } = deriveToken(vault.password, vault.machineHash);
-        const result = await api.write(vault.password, vault.machineHash, authToken, timestamp, service, generatedToken);
+        const { result } = await writeCredentialWithRecovery({
+          password: vault.password,
+          machineHash: vault.machineHash,
+          service,
+          value: generatedToken,
+          logFile: LOG_FILE,
+          normalize: false,
+        });
         if (result.error) return mcpError(result.error);
         return mcpResult(`Token generated and stored under "${service}": ${generatedToken}`);
       } catch (err) {
@@ -8058,8 +8258,87 @@ async function handleMcpTool(vault, name, args) {
     case "fs_mounts": {
       const { mounts, error } = await getFileserverMounts(vault);
       if (error) return mcpError(error);
-      if (!mounts || mounts.length === 0) return mcpResult("No fileserver mounts configured. Create one:\n1. Use clauth dashboard or clauth_enable to add a service with key_type='fileserver'\n2. Set the secret value to JSON: {\"path\": \"C:/Dev/regen-root\", \"access\": \"rwd\"}");
-      return mcpResult(JSON.stringify(mounts, null, 2));
+      if (!mounts || mounts.length === 0) return mcpResult("No fileserver mounts configured. Create one:\n1. Use clauth dashboard or clauth_enable to add a service with key_type='fileserver'\n2. Set the secret value to JSON: {\"path\": \"C:/Dev/regen-root\", \"access\": \"rwdg\"}  (add 'g' to allow the git verbs: fs_commit, fs_use_branch, fs_repo_status)");
+      // Decode the access string so callers know what's possible BEFORE trying —
+      // notably `git` (the git verbs require it; absent = explain how to enable).
+      const decorated = mounts.map((m) => {
+        const a = String(m.access || "");
+        return { ...m, can: { read: a.includes("r"), write: a.includes("w"), delete: a.includes("d"), git: a.includes("g") } };
+      });
+      return mcpResult(JSON.stringify(decorated, null, 2));
+    }
+
+    case "fs_repo_status": {
+      const r = await resolveInMount(".", args.mount, vault);
+      if (r.error) return mcpError(r.error);
+      if (!checkAccess(r.mount, "g")) return mcpError("Git access denied on this mount. Add 'g' to the mount's access string (e.g. 'rwdg') to enable the git verbs.");
+      try {
+        const { result, error } = await fsGit.repoStatus(r.resolved);
+        if (error) return mcpError(error);
+        return mcpResult(JSON.stringify(result, null, 2));
+      } catch (err) {
+        return mcpError(`Status failed: ${err.message}`);
+      }
+    }
+
+    case "fs_use_branch": {
+      const r = await resolveInMount(".", args.mount, vault);
+      if (r.error) return mcpError(r.error);
+      if (!checkAccess(r.mount, "g")) return mcpError("Git access denied on this mount. Add 'g' to the mount's access string (e.g. 'rwdg') to enable the git verbs.");
+      try {
+        const { result, error } = await fsGit.useBranch(r.resolved, args.branch, args.create === true);
+        if (error) return mcpError(error);
+        return mcpResult(JSON.stringify(result, null, 2));
+      } catch (err) {
+        return mcpError(`Branch switch failed: ${err.message}`);
+      }
+    }
+
+    case "fs_commit": {
+      const r = await resolveInMount(".", args.mount, vault);
+      if (r.error) return mcpError(r.error);
+      if (!checkAccess(r.mount, "g")) return mcpError("Git access denied on this mount. Add 'g' to the mount's access string (e.g. 'rwdg') to enable the git verbs.");
+      const push = args.push !== false;
+      const dryRun = args.dry_run === true;
+      // Fetch the push token from the vault up front (commit happens first, so
+      // a missing token still preserves the local commit). Skipped on dry-run.
+      let token = null, tokenError = null;
+      if (push && !dryRun) {
+        const sec = await vaultRetrieveValue(vault, "github");
+        if (sec.error || !sec.value) tokenError = `could not read the 'github' token (${sec.error || "empty"})`;
+        else token = sec.value;
+      }
+      try {
+        const { result, error } = await fsGit.commit(r.resolved, {
+          message: args.message,
+          paths: args.paths,
+          push,
+          dryRun,
+          expectedHead: args.expected_head,
+          remote: args.remote,
+          token,
+          tokenError,
+          authorName: args.author_name,
+          authorEmail: args.author_email,
+        });
+        if (error) return mcpError(error);
+        return mcpResult(JSON.stringify(result, null, 2));
+      } catch (err) {
+        return mcpError(`Commit failed: ${err.message}`);
+      }
+    }
+
+    case "fs_diff": {
+      const r = await resolveInMount(".", args.mount, vault);
+      if (r.error) return mcpError(r.error);
+      if (!checkAccess(r.mount, "g")) return mcpError("Git access denied on this mount. Add 'g' to the mount's access string (e.g. 'rwdg') to enable the git verbs.");
+      try {
+        const { result, error } = await fsGit.diff(r.resolved, { paths: args.paths, ref: args.ref, staged: args.staged === true });
+        if (error) return mcpError(error);
+        return mcpResult(JSON.stringify(result, null, 2));
+      } catch (err) {
+        return mcpError(`Diff failed: ${err.message}`);
+      }
     }
 
     case "monkey_dispatch": {
@@ -8251,6 +8530,7 @@ function createMcpServer(initPassword, whitelist) {
     whitelist,
     failCount: 0,
     MAX_FAILS: 10,
+    writeEnabled: process.env.CLAUTH_MCP_WRITE === "1",
   };
 
   const rl = createInterface({ input: process.stdin, terminal: false });
@@ -8289,7 +8569,7 @@ function createMcpServer(initPassword, whitelist) {
     if (msg.method === "tools/list") {
       return send({
         jsonrpc: "2.0", id,
-        result: { tools: MCP_TOOLS }
+        result: { tools: filterMcpToolsForWriteMode(MCP_TOOLS) }
       });
     }