@lifeaitools/clauth 1.5.84 → 1.7.1

package/cli/commands/watchdog.js

@@ -10,6 +10,13 @@ import fs from "fs";
 import path from "path";
 import os from "os";
 import { fileURLToPath } from "url";
+import {
+  getRegistryPath,
+  getWatchdogStatuses,
+  readWatchdogEvents,
+  registerWatchdogManifest,
+  restartWatchdogService,
+} from "../watchdog-registry.js";
 
 const __dirname  = path.dirname(fileURLToPath(import.meta.url));
 const TASK_NAME  = "ClautWatchdog";
@@ -26,9 +33,9 @@ function ensureWatchdogScript() {
 
 function isElevated() {
   try {
-    execSync(`${PS_EXE} -NoProfile -Command "[Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)"`,
+    const result = execSync(`${PS_EXE} -NoProfile -Command "([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)"`,
       { stdio: "pipe", encoding: "utf8" });
-    return true;
+    return result.trim().toLowerCase() === "true";
   } catch { return false; }
 }
 
@@ -55,10 +62,10 @@ function buildUnregisterCmd() {
 
 function runElevated(psCmd) {
   // Wrap in Start-Process -Verb RunAs to trigger UAC dialog
-  const inner = psCmd.replace(/"/g, '\\"');
+  const encoded = Buffer.from(psCmd, "utf16le").toString("base64");
   const result = spawnSync(PS_EXE, [
     "-NoProfile", "-Command",
-    `Start-Process '${PS_EXE}' -Verb RunAs -Wait -ArgumentList '-NoProfile -ExecutionPolicy Bypass -Command "${inner}"'`,
+    `Start-Process -FilePath '${PS_EXE}' -Verb RunAs -Wait -ArgumentList '-NoProfile -ExecutionPolicy Bypass -EncodedCommand ${encoded}'`,
   ], { stdio: "inherit", encoding: "utf8" });
   return result.status === 0;
 }
@@ -70,22 +77,80 @@ function runDirect(psCmd) {
   return result.status === 0;
 }
 
-export async function runWatchdog(action) {
+function readScheduledTaskState() {
+  try {
+    const out = execSync(
+      `${PS_EXE} -NoProfile -Command "Get-ScheduledTask -TaskName '${TASK_NAME}' -ErrorAction SilentlyContinue | Select-Object -ExpandProperty State"`,
+      { encoding: "utf8", stdio: ["pipe","pipe","pipe"], timeout: 5000 }
+    ).trim();
+    if (out) return out;
+  } catch {}
+
+  try {
+    const out = execSync(`schtasks /Query /TN ${TASK_NAME} /FO LIST`, {
+      encoding: "utf8",
+      stdio: ["pipe","pipe","pipe"],
+      timeout: 5000,
+    });
+    const status = out.match(/^Status:\\s*(.+)$/mi)?.[1]?.trim();
+    return status || "Registered";
+  } catch {
+    return null;
+  }
+}
+
+export async function runWatchdog(action, opts = {}) {
+  if (action === "register") {
+    const manifestPath = opts.manifest || opts.args?.[0];
+    if (!manifestPath) {
+      console.log("Usage: clauth watchdog register <manifest.json>");
+      return;
+    }
+    const manifest = JSON.parse(fs.readFileSync(path.resolve(manifestPath), "utf8"));
+    const result = registerWatchdogManifest(manifest);
+    console.log(`Registered ${result.registered} watchdog service(s): ${result.services.join(", ")}`);
+    console.log(`Registry: ${getRegistryPath()}`);
+    return;
+  }
+
+  if (action === "list" || action === "services") {
+    const status = await getWatchdogStatuses();
+    console.log(JSON.stringify(status, null, 2));
+    return;
+  }
+
+  if (action === "events") {
+    const limit = opts.limit ? Number(opts.limit) : 100;
+    console.log(JSON.stringify(readWatchdogEvents(limit), null, 2));
+    return;
+  }
+
+  if (action === "restart") {
+    const serviceId = opts.service || opts.args?.[0];
+    if (!serviceId) {
+      console.log("Usage: clauth watchdog restart <service-id>");
+      return;
+    }
+    const result = restartWatchdogService(serviceId);
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
   if (os.platform() !== "win32") {
     console.log("Watchdog auto-start is Windows-only. On Linux/macOS, use systemd or launchd.");
     return;
   }
 
   if (action === "status" || !action) {
+    const state = readScheduledTaskState();
     try {
-      const out = execSync(
-        `${PS_EXE} -NoProfile -Command "Get-ScheduledTask -TaskName '${TASK_NAME}' -ErrorAction SilentlyContinue | Select-Object -ExpandProperty State"`,
-        { encoding: "utf8", stdio: ["pipe","pipe","pipe"], timeout: 5000 }
-      ).trim();
-      if (out) {
-        console.log(`Watchdog task: ${TASK_NAME} — State: ${out}`);
+      if (state) {
+        console.log(`Watchdog task: ${TASK_NAME} — State: ${state}`);
         console.log(`Script:        ${DEST_PS1}`);
         console.log(`Log:           ${path.join(CLAUTH_DIR, "watchdog.log")}`);
+        const status = await getWatchdogStatuses();
+        console.log(`Services:      ${status.total} registered (${status.healthy} healthy, ${status.degraded} degraded, ${status.unreachable} unreachable)`);
+        console.log(`Registry:      ${getRegistryPath()}`);
       } else {
         console.log(`Watchdog task '${TASK_NAME}' is NOT registered.`);
         console.log("Run: clauth watchdog install");
@@ -105,7 +170,7 @@ export async function runWatchdog(action) {
     console.log("  Windows will ask for administrator approval — please click Yes.\n");
 
     const cmd = buildRegisterCmd(DEST_PS1);
-    const ok  = runElevated(cmd);
+    const ok  = isElevated() ? runDirect(cmd) : runElevated(cmd);
 
     if (ok) {
       console.log("\n  Watchdog installed. Starting now...");
@@ -124,7 +189,7 @@ export async function runWatchdog(action) {
   if (action === "uninstall") {
     console.log("\n  Removing clauth watchdog...");
     console.log("  Windows will ask for administrator approval — please click Yes.\n");
-    const ok = runElevated(buildUnregisterCmd());
+    const ok = isElevated() ? runDirect(buildUnregisterCmd()) : runElevated(buildUnregisterCmd());
     if (ok) console.log("\n  Watchdog removed.\n");
     else    console.log("\n  Removal cancelled or failed.\n");
     return;
@@ -140,5 +205,5 @@ export async function runWatchdog(action) {
     return;
   }
 
-  console.log("Usage: clauth watchdog [install|uninstall|status|start]");
+  console.log("Usage: clauth watchdog [install|uninstall|status|start|register|list|events|restart]");
 }

package/cli/index.js

@@ -9,6 +9,7 @@ import Conf from "conf";
 import { getConfOptions } from "./conf-path.js";
 import { getMachineHash, deriveToken, deriveSeedHash } from "./fingerprint.js";
 import * as api from "./api.js";
+import { writeCredentialWithRecovery } from "./recovery.js";
 import os from "os";
 import fs from "fs";
 import path from "path";
@@ -388,9 +389,18 @@ writeCmd
     }
     const spinner = ora(`Writing key for ${service}...`).start();
     try {
-      const result = await api.write(auth.password, auth.machineHash, auth.token, auth.timestamp, service, val);
+      const { result, snapshot, normalized } = await writeCredentialWithRecovery({
+        password: auth.password,
+        machineHash: auth.machineHash,
+        service,
+        value: val,
+      });
       if (result.error) throw new Error(result.error);
-      spinner.succeed(chalk.green(`Key stored in vault: auth.${service}`));
+      const details = [
+        snapshot?.ok ? "recovery snapshot written" : null,
+        normalized ? "value normalized" : null,
+      ].filter(Boolean);
+      spinner.succeed(chalk.green(`Key stored in vault: auth.${service}${details.length ? ` (${details.join(", ")})` : ""}`));
     } catch (err) {
       spinner.fail(chalk.red(err.message));
     }
@@ -637,11 +647,14 @@ Examples:
 // clauth watchdog
 // ──────────────────────────────────────────────
 program
-  .command("watchdog [action]")
-  .description("Manage auto-restart watchdog (install|uninstall|status|start)")
-  .action(async (action) => {
+  .command("watchdog [action] [args...]")
+  .description("Manage auto-restart watchdog (install|uninstall|status|start|register|list|events|restart)")
+  .option("--manifest <path>", "Watchdog service manifest for register")
+  .option("--service <id>", "Watchdog service id for restart")
+  .option("--limit <n>", "Event count for events", "100")
+  .action(async (action, args, opts) => {
     const { runWatchdog } = await import("./commands/watchdog.js");
-    await runWatchdog(action);
+    await runWatchdog(action, { ...opts, args });
   });
 
 // clauth doctor

package/cli/lib/fs-git.js

@@ -0,0 +1,217 @@
+/**
+ * fs-git.js — pure git operations behind the FS-MCP git verbs.
+ *
+ * No dependency on the vault, MCP transport, or mount resolution. The serve.js
+ * handlers resolve the mount + ACL, fetch the push token from the vault, then
+ * call these functions. Keeping the git logic here makes it directly testable
+ * against real repositories (see test-fs-git.mjs).
+ *
+ * Each high-level function returns { error } (→ caller emits an MCP error) or
+ * { result } (→ caller emits the JSON result). Fatal/unexpected git failures
+ * throw and are caught by the caller.
+ *
+ * NON-BLOCKING: every git invocation uses async spawn, never spawnSync, so the
+ * single-threaded clauth daemon keeps serving requests during a network push.
+ */
+import { spawn } from "child_process";
+import fs from "fs";
+import path from "path";
+
+// Branches the git verbs refuse to push to directly — humans promote these.
+export const FS_GIT_PROTECTED_BRANCHES = new Set(["main", "master", "production", "prod"]);
+
+// Async git runner. opts.label replaces args in error text (to hide auth
+// headers); opts.scrub redacts a substring from error detail before throwing.
+export function runGitAsync(cwd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("git", args, { cwd, windowsHide: true });
+    let out = "", err = "";
+    proc.stdout.on("data", (d) => { out += d.toString(); });
+    proc.stderr.on("data", (d) => { err += d.toString(); });
+    proc.on("error", reject);
+    proc.on("close", (code) => {
+      if (code !== 0) {
+        let detail = (err || out).trim();
+        if (opts.scrub) detail = detail.split(opts.scrub).join("***");
+        const what = opts.label || `git ${args.join(" ")}`;
+        return reject(new Error(`${what} failed${detail ? `: ${detail}` : ""}`));
+      }
+      resolve(out.trim());
+    });
+  });
+}
+
+// Push with an inline GitHub token injected as a one-shot Authorization header.
+// Token is NEVER persisted to git config, NEVER placed in the remote URL, and
+// is scrubbed from any error text.
+export function runGitPushAuthed(cwd, token, remote, refspec, extraArgs = []) {
+  const basic = Buffer.from(`x-access-token:${token}`).toString("base64");
+  const args = ["-c", `http.extraheader=AUTHORIZATION: basic ${basic}`, "push", ...extraArgs, remote, refspec];
+  return runGitAsync(cwd, args, { label: `git push ${remote} ${refspec}`, scrub: basic });
+}
+
+// Detect an in-progress merge or rebase in the repo at cwd.
+export async function gitInProgressState(cwd) {
+  let gitDir;
+  try { gitDir = await runGitAsync(cwd, ["rev-parse", "--git-dir"]); } catch { return { merge: false, rebase: false }; }
+  const gd = path.isAbsolute(gitDir) ? gitDir : path.join(cwd, gitDir);
+  const merge = fs.existsSync(path.join(gd, "MERGE_HEAD"));
+  const rebase = fs.existsSync(path.join(gd, "rebase-merge")) || fs.existsSync(path.join(gd, "rebase-apply"));
+  return { merge, rebase };
+}
+
+function normalizeRepoPath(p) {
+  if (!p || typeof p !== "string") return null;
+  const normalized = p.replace(/\\/g, "/").replace(/^\/+/, "");
+  const parts = normalized.split("/").filter(Boolean);
+  if (parts.length === 0 || parts.includes("..") || path.isAbsolute(p)) return null;
+  return parts.join("/");
+}
+
+async function aheadBehind(repoRoot) {
+  try {
+    const counts = await runGitAsync(repoRoot, ["rev-list", "--left-right", "--count", "@{u}...HEAD"]);
+    const [b, a] = counts.split(/\s+/);
+    return { behind: Number(b), ahead: Number(a) };
+  } catch {
+    return { behind: null, ahead: null };
+  }
+}
+
+/** Current git state of the repo in one call. */
+export async function repoStatus(repoRoot) {
+  const topLevel = path.normalize(await runGitAsync(repoRoot, ["rev-parse", "--show-toplevel"]));
+  const branch = await runGitAsync(repoRoot, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const head = await runGitAsync(repoRoot, ["rev-parse", "HEAD"]);
+  const headShort = await runGitAsync(repoRoot, ["rev-parse", "--short", "HEAD"]);
+  let subject = ""; try { subject = await runGitAsync(repoRoot, ["log", "-1", "--pretty=%s"]); } catch {}
+  const porcelain = await runGitAsync(repoRoot, ["status", "--porcelain"]);
+  const dirty = porcelain ? porcelain.split("\n").map((l) => l.trim()).filter(Boolean) : [];
+  const stagedRaw = await runGitAsync(repoRoot, ["diff", "--cached", "--name-only"]);
+  let upstream = null;
+  try { upstream = await runGitAsync(repoRoot, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]); } catch {}
+  const { ahead, behind } = await aheadBehind(repoRoot);
+  const prog = await gitInProgressState(repoRoot);
+  return {
+    result: {
+      branch, head, head_short: headShort, subject,
+      clean: dirty.length === 0,
+      dirty_count: dirty.length,
+      dirty_paths: dirty.slice(0, 100),
+      staged_paths: stagedRaw ? stagedRaw.split("\n").filter(Boolean) : [],
+      upstream, ahead, behind,
+      merge_in_progress: prog.merge,
+      rebase_in_progress: prog.rebase,
+      repo_root: topLevel,
+    },
+  };
+}
+
+/** Safely switch to (or create) a branch. */
+export async function useBranch(repoRoot, branch, create) {
+  branch = (branch || "").trim();
+  if (!branch) return { error: "branch is required" };
+  const prog = await gitInProgressState(repoRoot);
+  if (prog.merge || prog.rebase) return { error: "Refused: a merge or rebase is in progress. Finish or abort it before switching branches." };
+  let exists = true;
+  try { await runGitAsync(repoRoot, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]); } catch { exists = false; }
+  if (create && exists) return { error: `Branch already exists: ${branch}. Call again with create=false to switch to it.` };
+  if (!create && !exists) return { error: `Branch does not exist: ${branch}. Call again with create=true to create it from HEAD.` };
+  if (create) {
+    await runGitAsync(repoRoot, ["switch", "-c", branch]);
+  } else {
+    try {
+      await runGitAsync(repoRoot, ["switch", branch]);
+    } catch (e) {
+      return { error: `Cannot switch to ${branch}: ${e.message}. Commit your changes with fs_commit first — your working tree was left untouched.` };
+    }
+  }
+  const headShort = await runGitAsync(repoRoot, ["rev-parse", "--short", "HEAD"]);
+  return { result: { status: "ok", branch, created: !!create, head_short: headShort } };
+}
+
+/**
+ * Stage + commit (+ push by default).
+ * opts: { message, paths?, push=true, remote="origin", token?, tokenError?, authorName?, authorEmail? }
+ * token/tokenError are supplied by the caller after a vault lookup; commit
+ * happens first, then push, so the no-token case still preserves the commit.
+ */
+export async function commit(repoRoot, opts = {}) {
+  const message = (opts.message || "").trim();
+  if (!message) return { error: "message is required" };
+  const push = opts.push !== false;
+  const remote = opts.remote || "origin";
+
+  const topLevel = path.normalize(await runGitAsync(repoRoot, ["rev-parse", "--show-toplevel"]));
+  if (topLevel.toLowerCase() !== path.normalize(repoRoot).toLowerCase()) {
+    return { error: `Mount root is not the git repo root: ${repoRoot} (repo root: ${topLevel})` };
+  }
+  const prog = await gitInProgressState(repoRoot);
+  if (prog.merge || prog.rebase) return { error: "Refused: a merge or rebase is in progress. Resolve conflicts and finish it before committing." };
+  const branch = await runGitAsync(repoRoot, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  if (branch === "HEAD") return { error: "Refused: detached HEAD. Use fs_use_branch to get on a branch first." };
+
+  // Stage
+  if (Array.isArray(opts.paths) && opts.paths.length > 0) {
+    if (opts.paths.length > 100) return { error: "Too many paths: max 100 per commit" };
+    const norm = [];
+    for (const p of opts.paths) {
+      const n = normalizeRepoPath(p);
+      if (!n) return { error: `Invalid repo path: ${p}` };
+      norm.push(n);
+    }
+    await runGitAsync(repoRoot, ["add", "--", ...norm]);
+  } else {
+    await runGitAsync(repoRoot, ["add", "-A"]);
+  }
+  const stagedRaw = await runGitAsync(repoRoot, ["diff", "--cached", "--name-only"]);
+  if (!stagedRaw) {
+    const headShort = await runGitAsync(repoRoot, ["rev-parse", "--short", "HEAD"]);
+    return { result: { status: "nothing_to_commit", branch, head_short: headShort, message: "No changes in the requested scope; nothing was committed." } };
+  }
+  const committedFiles = stagedRaw.split("\n").filter(Boolean);
+
+  await runGitAsync(repoRoot, [
+    "-c", `user.name=${opts.authorName || "clauth-fs"}`,
+    "-c", `user.email=${opts.authorEmail || "fs@clauth.local"}`,
+    "commit", "-m", message,
+  ]);
+  const commitSha = await runGitAsync(repoRoot, ["rev-parse", "HEAD"]);
+  const commitShort = await runGitAsync(repoRoot, ["rev-parse", "--short", "HEAD"]);
+  const base = { branch, commit: commitSha, commit_short: commitShort, files: committedFiles };
+
+  if (!push) {
+    return { result: { status: "committed_local", ...base, pushed: false, message: `Committed ${committedFiles.length} file(s) locally as ${commitShort}.` } };
+  }
+  if (FS_GIT_PROTECTED_BRANCHES.has(branch.toLowerCase())) {
+    return { result: { status: "committed_local_not_pushed", ...base, pushed: false, push_blocked: "protected_branch", message: `Commit saved locally as ${commitShort}. Push refused: '${branch}' is protected — a human promotes it. Use fs_use_branch to move to a feature/develop branch to push directly.` } };
+  }
+  if (!opts.token) {
+    return { result: { status: "committed_local_not_pushed", ...base, pushed: false, push_blocked: "no_token", message: `Commit saved locally as ${commitShort}. Push blocked: ${opts.tokenError || "no github token available"}.` } };
+  }
+  const token = opts.token.trim();
+
+  try {
+    await runGitPushAuthed(repoRoot, token, remote, `HEAD:${branch}`);
+  } catch (e1) {
+    // Branch likely diverged — integrate then retry once.
+    try { await runGitAsync(repoRoot, ["fetch", "--no-tags", remote, branch]); } catch { /* branch may not exist on remote yet */ }
+    try {
+      await runGitAsync(repoRoot, ["rebase", `${remote}/${branch}`]);
+    } catch {
+      try { await runGitAsync(repoRoot, ["rebase", "--abort"]); } catch {}
+      return { result: { status: "committed_local_not_pushed", ...base, pushed: false, push_blocked: "diverged", message: `Commit saved locally as ${commitShort}. Push blocked: '${branch}' diverged from ${remote} and auto-rebase hit conflicts (rebase aborted, tree restored). A human should reconcile.` } };
+    }
+    try {
+      await runGitPushAuthed(repoRoot, token, remote, `HEAD:${branch}`);
+    } catch (e2) {
+      const sha2 = await runGitAsync(repoRoot, ["rev-parse", "--short", "HEAD"]);
+      return { result: { status: "committed_local_not_pushed", ...base, commit_short: sha2, pushed: false, push_blocked: "push_failed", message: `Commit saved and rebased locally (${sha2}) but the push still failed: ${e2.message}` } };
+    }
+  }
+
+  const finalSha = await runGitAsync(repoRoot, ["rev-parse", "HEAD"]);
+  const finalShort = await runGitAsync(repoRoot, ["rev-parse", "--short", "HEAD"]);
+  const { ahead, behind } = await aheadBehind(repoRoot);
+  return { result: { status: "committed_and_pushed", branch, commit: finalSha, commit_short: finalShort, files: committedFiles, pushed: true, remote, ahead, behind, message: `Committed and pushed ${committedFiles.length} file(s) to ${remote}/${branch} as ${finalShort}.` } };
+}

package/cli/recovery.js

@@ -0,0 +1,101 @@
+import crypto from "crypto";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { getConfOptions } from "./conf-path.js";
+import { deriveToken } from "./fingerprint.js";
+import * as api from "./api.js";
+
+const RECOVERY_VERSION = 1;
+
+function getRecoveryDir() {
+  const opts = getConfOptions();
+  if (opts.cwd) return path.join(opts.cwd, "recovery");
+  return path.join(os.homedir(), ".config", "clauth", "recovery");
+}
+
+function hashValue(value) {
+  return crypto.createHash("sha256").update(String(value), "utf8").digest("hex");
+}
+
+function deriveRecoveryKey(password, machineHash, salt) {
+  return crypto.scryptSync(`${password}:${machineHash}`, salt, 32);
+}
+
+function safeServiceName(service) {
+  return String(service || "unknown").replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+export function normalizeCredentialValue(value, { keyType = "", service = "" } = {}) {
+  if (typeof value !== "string") return value;
+  const text = value.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const looksPem = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/.test(text);
+  const looksSsh = String(keyType).toLowerCase() === "ssh" || /ssh|pem|private/i.test(service);
+  if (!looksPem && !looksSsh) return value;
+  return text.replace(/\n*$/, "\n");
+}
+
+export async function snapshotCredentialBeforeWrite({ password, machineHash, service, logFile }) {
+  if (!password || !machineHash || !service) return { ok: false, skipped: "missing_context" };
+
+  let current;
+  try {
+    const { token, timestamp } = deriveToken(password, machineHash);
+    current = await api.retrieve(password, machineHash, token, timestamp, service);
+  } catch (err) {
+    return { ok: false, skipped: "retrieve_failed", error: err.message };
+  }
+
+  if (current?.error || current?.value === undefined || current?.value === null) {
+    return { ok: false, skipped: current?.error || "no_existing_value" };
+  }
+
+  const value = typeof current.value === "string" ? current.value : JSON.stringify(current.value);
+  const now = new Date().toISOString();
+  const salt = crypto.randomBytes(16);
+  const iv = crypto.randomBytes(12);
+  const key = deriveRecoveryKey(password, machineHash, salt);
+  const meta = {
+    version: RECOVERY_VERSION,
+    service,
+    key_type: current.key_type || null,
+    created_at: now,
+    value_sha256: hashValue(value),
+  };
+
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  cipher.setAAD(Buffer.from(JSON.stringify(meta), "utf8"));
+  const ciphertext = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+
+  const payload = {
+    ...meta,
+    kdf: "scrypt",
+    cipher: "aes-256-gcm",
+    salt: salt.toString("base64"),
+    iv: iv.toString("base64"),
+    tag: tag.toString("base64"),
+    ciphertext: ciphertext.toString("base64"),
+  };
+
+  const dir = getRecoveryDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const stamp = now.replace(/[-:.]/g, "").replace("T", "-").replace("Z", "");
+  const filePath = path.join(dir, `${stamp}-${safeServiceName(service)}.json`);
+  fs.writeFileSync(filePath, JSON.stringify(payload, null, 2) + "\n", { mode: 0o600 });
+
+  if (logFile) {
+    try { fs.appendFileSync(logFile, `[${now}] Recovery snapshot written for ${service}: ${filePath}\n`); } catch {}
+  }
+  return { ok: true, filePath, value_sha256: meta.value_sha256 };
+}
+
+export async function writeCredentialWithRecovery({ password, machineHash, service, value, logFile, normalize = true }) {
+  const { token, timestamp } = deriveToken(password, machineHash);
+  const status = await api.status(password, machineHash, token, timestamp);
+  const svc = (status.services || []).find(s => String(s.name || "").toLowerCase() === String(service || "").toLowerCase());
+  const normalizedValue = normalize ? normalizeCredentialValue(value, { keyType: svc?.key_type, service }) : value;
+  const snapshot = await snapshotCredentialBeforeWrite({ password, machineHash, service, logFile });
+  const result = await api.write(password, machineHash, token, timestamp, service, normalizedValue);
+  return { result, snapshot, normalized: normalizedValue !== value };
+}