agentlas 1.0.65 → 1.0.67

package/engine/project/credentials.cjs

@@ -10,9 +10,257 @@
  */
 const fs = require("node:fs");
 const path = require("node:path");
+const crypto = require("node:crypto");
 const { loadArch } = require("../core/db.cjs");
 const { runCwd } = require("./paths.cjs");
 
+const MAX_MANAGED_CREDENTIAL_METADATA_BYTES = 1024 * 1024;
+const MAX_CREDENTIAL_FILE_BYTES = 16 * 1024 * 1024;
+const CREDENTIAL_NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
+const credentialDestinationBindings = new Map();
+
+function credentialSameDirectoryIdentity(left, right) {
+  return Boolean(
+    left && right && left.isDirectory() && right.isDirectory() &&
+    !left.isSymbolicLink() && !right.isSymbolicLink() &&
+    left.dev === right.dev && left.ino === right.ino,
+  );
+}
+
+function credentialDirectoryAnchor(target, label, containedBy = null) {
+  const stat = fs.lstatSync(target);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`${label} must be a real managed directory`);
+  const realpath = fs.realpathSync.native(target);
+  if (containedBy && !(
+    realpath === containedBy.realpath || realpath.startsWith(`${containedBy.realpath}${path.sep}`)
+  )) throw new Error(`${label} escaped the managed project`);
+  return { path: target, realpath, dev: stat.dev, ino: stat.ino, stat };
+}
+
+function credentialAssertDirectoryAnchor(anchor, label, containedBy = null) {
+  const current = credentialDirectoryAnchor(anchor.path, label, containedBy);
+  if (!credentialSameDirectoryIdentity(anchor.stat || anchor, current.stat || current) || current.realpath !== anchor.realpath) {
+    throw new Error(`${label} changed while it was being used`);
+  }
+  return current;
+}
+
+function credentialSameFileIdentity(left, right) {
+  return Boolean(
+    left && right && left.isFile() && right.isFile() &&
+    !left.isSymbolicLink() && !right.isSymbolicLink() &&
+    left.dev === right.dev && left.ino === right.ino,
+  );
+}
+
+function credentialSameFileSnapshot(left, right) {
+  return credentialSameFileIdentity(left, right) && left.nlink === right.nlink &&
+    left.size === right.size && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs;
+}
+
+function credentialFileSnapshot(file, label, { allowMissing = false, allowHardLinks = false } = {}) {
+  let stat;
+  try { stat = fs.lstatSync(file); }
+  catch (error) {
+    if (allowMissing && error && error.code === "ENOENT") return null;
+    throw error;
+  }
+  if (!stat.isFile() || stat.isSymbolicLink() || (!allowHardLinks && stat.nlink !== 1) || stat.size > MAX_CREDENTIAL_FILE_BYTES) {
+    throw new Error(`${label} must be a bounded regular non-symbolic-link file`);
+  }
+  return stat;
+}
+
+function credentialRemoveOwnedFile(file, expected, { allowLinked = false } = {}) {
+  try {
+    const current = fs.lstatSync(file);
+    if (credentialSameFileIdentity(current, expected) && (current.nlink === 1 || (allowLinked && current.nlink >= 2))) {
+      fs.unlinkSync(file);
+    }
+  } catch { /* leave unknown successors and recovery artifacts untouched */ }
+}
+
+function credentialRestoreBackup(backup, target, expected, parent) {
+  try {
+    credentialAssertDirectoryAnchor(parent, "credential destination directory");
+    if (credentialFileSnapshot(target, "credential destination successor", { allowMissing: true })) return false;
+    const current = credentialFileSnapshot(backup, "credential destination backup");
+    if (!current || !credentialSameFileIdentity(current, expected) || current.nlink !== 1) return false;
+    fs.linkSync(backup, target);
+    const restored = credentialFileSnapshot(target, "credential destination restored", { allowHardLinks: true });
+    if (!restored || !credentialSameFileIdentity(restored, expected) || restored.nlink < 2) return false;
+    fs.unlinkSync(backup);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function credentialPublishFile(parent, targetName, temporary, expected) {
+  credentialAssertDirectoryAnchor(parent, "credential destination directory");
+  const target = path.join(parent.realpath, targetName);
+  const current = credentialFileSnapshot(target, "credential destination", { allowMissing: true });
+  if ((expected && (!current || !credentialSameFileSnapshot(current, expected))) || (!expected && current)) {
+    throw new Error("credential destination changed before replacement");
+  }
+  let backup = null;
+  let linked = false;
+  try {
+    if (expected) {
+      backup = `${target}.previous-${process.pid}-${crypto.randomUUID()}`;
+      fs.renameSync(target, backup);
+      const moved = credentialFileSnapshot(backup, "credential destination backup");
+      if (!moved || !credentialSameFileIdentity(moved, expected) || moved.nlink !== 1) {
+        credentialRestoreBackup(backup, target, expected, parent);
+        throw new Error("credential destination changed before replacement");
+      }
+      credentialAssertDirectoryAnchor(parent, "credential destination directory");
+      if (credentialFileSnapshot(target, "credential destination successor", { allowMissing: true })) {
+        throw new Error("credential destination successor appeared during replacement");
+      }
+    }
+    credentialAssertDirectoryAnchor(parent, "credential destination directory");
+    if (credentialFileSnapshot(target, "credential destination successor", { allowMissing: true })) {
+      throw new Error("credential destination successor appeared during replacement");
+    }
+    fs.linkSync(temporary.path, target);
+    linked = true;
+    const linkedTarget = credentialFileSnapshot(target, "credential destination", { allowHardLinks: true });
+    if (!linkedTarget || !credentialSameFileIdentity(linkedTarget, temporary.stat) || linkedTarget.nlink < 2) {
+      throw new Error("credential publication produced an unsafe target");
+    }
+    credentialAssertDirectoryAnchor(parent, "credential destination directory");
+    credentialRemoveOwnedFile(temporary.path, temporary.stat, { allowLinked: true });
+    const installed = credentialFileSnapshot(target, "credential destination");
+    if (!installed || !credentialSameFileIdentity(installed, temporary.stat) || installed.nlink !== 1) {
+      throw new Error("credential publication identity changed");
+    }
+    try { fs.chmodSync(target, 0o600); } catch { /* Windows/best-effort */ }
+    const final = credentialFileSnapshot(target, "credential destination");
+    if (!final || !credentialSameFileIdentity(final, temporary.stat) || final.nlink !== 1 ||
+        (process.platform !== "win32" && (final.mode & 0o777) !== 0o600)) {
+      throw new Error("credential publication mode or identity changed");
+    }
+    credentialAssertDirectoryAnchor(parent, "credential destination directory");
+    if (backup) {
+      const backupStat = credentialFileSnapshot(backup, "credential destination backup", { allowMissing: true });
+      if (backupStat && credentialSameFileIdentity(backupStat, expected) && backupStat.nlink === 1) fs.unlinkSync(backup);
+    }
+    return target;
+  } catch (error) {
+    if (linked) credentialRemoveOwnedFile(target, temporary.stat);
+    credentialRemoveOwnedFile(temporary.path, temporary.stat);
+    if (backup) credentialRestoreBackup(backup, target, expected, parent);
+    throw error;
+  }
+}
+
+function credentialProjectRootCli(projectPath) {
+  const requested = path.resolve(projectPath || "");
+  const root = fs.realpathSync.native(requested);
+  const stat = fs.statSync(root);
+  if (!stat.isDirectory()) throw new Error("credential project must be a real directory");
+  return root;
+}
+
+function ensureManagedDirectoryCli(root, relativePath, mode = 0o700) {
+  let current = root;
+  for (const segment of String(relativePath || "").split(/[\\/]+/).filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      const stat = fs.lstatSync(current);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("credential store directories must not be symbolic links");
+    } catch (error) {
+      if (!error || error.code !== "ENOENT") throw error;
+      fs.mkdirSync(current, { recursive: false, mode });
+    }
+  }
+  return current;
+}
+
+function readManagedTextSnapshotCli(filePath, maxBytes = MAX_MANAGED_CREDENTIAL_METADATA_BYTES) {
+  let before;
+  try { before = fs.lstatSync(filePath); }
+  catch (error) {
+    if (error && error.code === "ENOENT") return { exists: false, text: "", mode: 0o600 };
+    throw error;
+  }
+  if (!before.isFile() || before.isSymbolicLink() || before.size > maxBytes) {
+    throw new Error("credential store file must be a bounded regular non-symbolic-link file");
+  }
+  const fd = fs.openSync(filePath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+  try {
+    const opened = fs.fstatSync(fd);
+    if (!opened.isFile() || opened.size > maxBytes || opened.dev !== before.dev || opened.ino !== before.ino) {
+      throw new Error("credential store file changed while opening");
+    }
+    return {
+      exists: true,
+      text: fs.readFileSync(fd, "utf8"),
+      mode: before.mode & 0o777,
+      stat: before,
+    };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function assertManagedSnapshotUnchangedCli(filePath, snapshot) {
+  let current;
+  try { current = fs.lstatSync(filePath); }
+  catch (error) {
+    if (error && error.code === "ENOENT" && !snapshot.exists) return;
+    throw new Error("credential store file changed before replacement");
+  }
+  if (
+    !snapshot.exists || !current.isFile() || current.isSymbolicLink() || !snapshot.stat ||
+    current.dev !== snapshot.stat.dev || current.ino !== snapshot.stat.ino ||
+    current.size !== snapshot.stat.size || current.mtimeMs !== snapshot.stat.mtimeMs
+  ) throw new Error("credential store file changed before replacement");
+}
+
+function replaceManagedFileCli(tempPath, filePath, snapshot) {
+  assertManagedSnapshotUnchangedCli(filePath, snapshot);
+  try {
+    fs.renameSync(tempPath, filePath);
+    return;
+  } catch (error) {
+    if (
+      process.platform !== "win32" || !snapshot.exists ||
+      !["EEXIST", "EPERM", "EACCES"].includes(error && error.code)
+    ) throw error;
+  }
+  assertManagedSnapshotUnchangedCli(filePath, snapshot);
+  const backup = `${filePath}.agentlas-${process.pid}-${crypto.randomUUID()}.bak`;
+  fs.renameSync(filePath, backup);
+  try {
+    fs.renameSync(tempPath, filePath);
+  } catch (error) {
+    try { if (!fs.existsSync(filePath)) fs.renameSync(backup, filePath); } catch { /* leave recoverable backup */ }
+    throw error;
+  }
+  try { fs.rmSync(backup, { force: true }); } catch { /* committed target is authoritative */ }
+}
+
+function writeManagedTextAtomicCli(filePath, text, options = {}) {
+  const snapshot = options.snapshot || readManagedTextSnapshotCli(filePath, options.maxBytes);
+  const bytes = Buffer.byteLength(text, "utf8");
+  if (bytes > (options.maxBytes || MAX_MANAGED_CREDENTIAL_METADATA_BYTES)) throw new Error("credential store file exceeds its safety limit");
+  const temp = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  try {
+    fs.writeFileSync(temp, text, { encoding: "utf8", mode: options.mode || snapshot.mode || 0o600, flag: "wx" });
+    replaceManagedFileCli(temp, filePath, snapshot);
+  } finally {
+    try { fs.rmSync(temp, { force: true }); } catch { /* best-effort cleanup */ }
+  }
+}
+
+function ensureManagedTextFileCli(filePath, content, mode = 0o600) {
+  const snapshot = readManagedTextSnapshotCli(filePath);
+  if (!snapshot.exists) writeManagedTextAtomicCli(filePath, content, { snapshot, mode });
+  return snapshot.exists ? snapshot.text : content;
+}
+
 function localCredentialConfigCli(arch) {
   return {
     mapFile: arch.localCredentialsMapFile || "local-credentials.map.json",
@@ -94,24 +342,24 @@ ${credentialIndexSectionContentCli(arch)}
 `;
 }
 function ensureSoulCredentialIndexCli(projectPath, projectName, arch) {
+  const root = credentialProjectRootCli(projectPath);
   const memoryDir = (arch && arch.memoryDir) || ".agentlas";
   const soulFile = (arch && arch.soulFile) || "project-soul-memory.md";
-  const dir = path.join(projectPath, memoryDir);
+  const dir = ensureManagedDirectoryCli(root, memoryDir);
   const soul = path.join(dir, soulFile);
-  fs.mkdirSync(dir, { recursive: true });
-  if (!fs.existsSync(soul)) {
-    fs.writeFileSync(soul, projectSoulTemplateCli(projectName, arch), "utf8");
+  const snapshot = readManagedTextSnapshotCli(soul);
+  if (!snapshot.exists) {
+    writeManagedTextAtomicCli(soul, projectSoulTemplateCli(projectName, arch), { snapshot, mode: 0o600 });
     return soul;
   }
-  let content = "";
-  try { content = fs.readFileSync(soul, "utf8"); } catch { content = ""; }
+  const content = snapshot.text;
   if (!content.includes(CREDENTIAL_INDEX_SECTION_CLI)) {
     const section = credentialIndexSectionContentCli(arch);
     const marker = "\n## Project Purpose";
     const next = content.includes(marker)
       ? content.replace(marker, `\n${section}\n## Project Purpose`)
       : `${content.trimEnd()}\n\n${section}\n`;
-    fs.writeFileSync(soul, next.endsWith("\n") ? next : next + "\n", "utf8");
+    writeManagedTextAtomicCli(soul, next.endsWith("\n") ? next : next + "\n", { snapshot, mode: 0o600 });
   }
   return soul;
 }
@@ -157,7 +405,8 @@ Do not commit files from this folder.
 `;
 }
 function ensureAgentlasCredentialIgnoreCli(projectPath, cfg) {
-  const gitignorePath = path.join(projectPath, ".gitignore");
+  const root = credentialProjectRootCli(projectPath);
+  const gitignorePath = path.join(root, ".gitignore");
   const marker = "# Agentlas local credentials";
   const block = `${marker}
 .env
@@ -171,45 +420,62 @@ ${cfg.credentialsDir}/*
 !${cfg.credentialsDir}/
 !${cfg.credentialsDir}/${cfg.readmeFile}
 `;
-  let existing = "";
-  try { existing = fs.readFileSync(gitignorePath, "utf8"); } catch { existing = ""; }
+  const snapshot = readManagedTextSnapshotCli(gitignorePath);
+  const existing = snapshot.text;
   if (existing.includes(marker)) {
-    if (!/^\._\*$/m.test(existing)) fs.writeFileSync(gitignorePath, `${existing.trimEnd()}\n._*\n`, "utf8");
+    if (!/^\._\*$/m.test(existing)) {
+      writeManagedTextAtomicCli(gitignorePath, `${existing.trimEnd()}\n._*\n`, { snapshot, mode: snapshot.mode || 0o644 });
+    }
     return;
   }
   const next = existing.trimEnd() ? `${existing.trimEnd()}\n\n${block}` : block;
-  fs.writeFileSync(gitignorePath, next.endsWith("\n") ? next : next + "\n", "utf8");
+  writeManagedTextAtomicCli(gitignorePath, next.endsWith("\n") ? next : next + "\n", {
+    snapshot,
+    mode: snapshot.exists ? snapshot.mode : 0o644,
+  });
 }
 function ensureLocalCredentialStoreCli(projectPath, projectName, arch) {
+  const root = credentialProjectRootCli(projectPath);
   const cfg = localCredentialConfigCli(arch || loadArch());
-  const dir = path.join(projectPath, (arch && arch.memoryDir) || ".agentlas");
-  fs.mkdirSync(dir, { recursive: true });
-  fs.mkdirSync(path.join(projectPath, cfg.signingDir), { recursive: true });
-  fs.mkdirSync(path.join(projectPath, cfg.credentialsDir), { recursive: true });
-  const envExample = path.join(projectPath, cfg.envExampleFile);
-  if (!fs.existsSync(envExample)) fs.writeFileSync(envExample, envExampleContentCli(cfg), "utf8");
-  const signingReadme = path.join(projectPath, cfg.signingDir, cfg.readmeFile);
-  if (!fs.existsSync(signingReadme)) fs.writeFileSync(signingReadme, signingReadmeContentCli(cfg), "utf8");
-  const credentialsReadme = path.join(projectPath, cfg.credentialsDir, cfg.readmeFile);
-  if (!fs.existsSync(credentialsReadme)) fs.writeFileSync(credentialsReadme, credentialsReadmeContentCli(cfg), "utf8");
+  const dir = ensureManagedDirectoryCli(root, (arch && arch.memoryDir) || ".agentlas");
+  const signingDir = ensureManagedDirectoryCli(root, cfg.signingDir);
+  const credentialsDir = ensureManagedDirectoryCli(root, cfg.credentialsDir);
+  const envExample = path.join(root, cfg.envExampleFile);
+  ensureManagedTextFileCli(envExample, envExampleContentCli(cfg), 0o600);
+  const signingReadme = path.join(signingDir, cfg.readmeFile);
+  ensureManagedTextFileCli(signingReadme, signingReadmeContentCli(cfg), 0o600);
+  const credentialsReadme = path.join(credentialsDir, cfg.readmeFile);
+  ensureManagedTextFileCli(credentialsReadme, credentialsReadmeContentCli(cfg), 0o600);
   const mapPath = path.join(dir, cfg.mapFile);
-  if (!fs.existsSync(mapPath)) {
-    fs.writeFileSync(mapPath, JSON.stringify(localCredentialsMapSkeletonCli(projectPath, projectName, cfg), null, 2) + "\n", "utf8");
+  const mapText = ensureManagedTextFileCli(
+    mapPath,
+    JSON.stringify(localCredentialsMapSkeletonCli(root, projectName, cfg), null, 2) + "\n",
+    0o600,
+  );
+  let mapValue;
+  try { mapValue = JSON.parse(mapText); }
+  catch (error) { throw new Error(`credential map is invalid JSON: ${String((error && error.message) || error)}`); }
+  if (!mapValue || typeof mapValue !== "object" || Array.isArray(mapValue)) {
+    throw new Error("credential map must contain a JSON object");
   }
-  ensureAgentlasCredentialIgnoreCli(projectPath, cfg);
-  return { cfg, mapPath };
+  ensureAgentlasCredentialIgnoreCli(root, cfg);
+  return { cfg, mapPath, projectRoot: root };
 }
-function readJsonObjectCli(file, fallback) {
+function readJsonObjectCli(file, fallback, options = {}) {
   try {
-    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : fallback;
-  } catch {
+    const parsed = JSON.parse(readManagedTextSnapshotCli(file).text);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+    if (options.strict) throw new Error("credential map must contain a JSON object");
+    return fallback;
+  } catch (error) {
+    if (options.strict) throw new Error(`credential map is unreadable or invalid: ${String((error && error.message) || error)}`);
     return fallback;
   }
 }
 function upsertLocalCredentialMapCli(projectPath, projectName, arch, entry) {
-  const { cfg, mapPath } = ensureLocalCredentialStoreCli(projectPath, projectName, arch || loadArch());
-  const data = readJsonObjectCli(mapPath, localCredentialsMapSkeletonCli(projectPath, projectName, cfg));
+  const { cfg, mapPath, projectRoot } = ensureLocalCredentialStoreCli(projectPath, projectName, arch || loadArch());
+  const snapshot = readManagedTextSnapshotCli(mapPath);
+  const data = readJsonObjectCli(mapPath, localCredentialsMapSkeletonCli(projectPath, projectName, cfg), { strict: true });
   const now = new Date().toISOString();
   data.updatedAt = now;
   if (!Array.isArray(data.entries)) data.entries = [];
@@ -230,17 +496,96 @@ function upsertLocalCredentialMapCli(projectPath, projectName, arch, entry) {
   const idx = data.entries.findIndex((row) => row && row.id === id);
   if (idx >= 0) data.entries[idx] = { ...data.entries[idx], ...clean };
   else data.entries.push(clean);
-  fs.writeFileSync(mapPath, JSON.stringify(data, null, 2) + "\n", "utf8");
+  data.projectRoot = projectRoot;
+  writeManagedTextAtomicCli(mapPath, JSON.stringify(data, null, 2) + "\n", { snapshot, mode: 0o600 });
 }
 // v1은 fail()로 즉시 종료했다 — v2 규칙은 throw → 명령이 ctx.err + return 1 로 변환.
 function safeCredentialDestRelCli(destRel) {
   const rel = path.normalize(String(destRel || "")).replace(/\\/g, "/");
-  if (!rel || path.isAbsolute(rel) || rel === "." || rel.startsWith("../") || rel.includes("\0")) {
+  if (!rel || path.isAbsolute(rel) || rel === "." || rel.startsWith("../") || /[\u0000-\u001f\u007f]/.test(rel)) {
     throw new Error("credential destination must be a relative path inside the project");
   }
   return rel;
 }
 
+function resolveCredentialDestinationCli(projectPath, destRel) {
+  const root = credentialProjectRootCli(projectPath);
+  const rel = safeCredentialDestRelCli(destRel);
+  const rootAnchor = credentialDirectoryAnchor(root, "credential project root");
+  const parentRel = path.dirname(rel);
+  const parent = parentRel === "." ? root : ensureManagedDirectoryCli(root, parentRel);
+  const realParent = fs.realpathSync.native(parent);
+  const relativeParent = path.relative(root, realParent);
+  if (path.isAbsolute(relativeParent) || relativeParent === ".." || relativeParent.startsWith(`..${path.sep}`)) {
+    throw new Error("credential destination escaped the project");
+  }
+  const parentAnchor = credentialDirectoryAnchor(realParent, "credential destination directory", rootAnchor);
+  const destination = path.join(parentAnchor.realpath, path.basename(rel));
+  credentialDestinationBindings.set(path.resolve(destination), {
+    root: rootAnchor,
+    parent: parentAnchor,
+  });
+  return destination;
+}
+
+function copyCredentialFileAtomicCli(sourcePath, destinationPath, options = {}) {
+  const resolvedDestination = path.resolve(destinationPath);
+  const binding = credentialDestinationBindings.get(resolvedDestination) || null;
+  try {
+    const source = fs.realpathSync.native(path.resolve(sourcePath));
+    const sourceStat = fs.statSync(source);
+    if (!sourceStat.isFile() || sourceStat.size <= 0 || sourceStat.size > MAX_CREDENTIAL_FILE_BYTES) {
+      throw new Error("credential source must be a non-empty regular file no larger than 16 MiB");
+    }
+    const root = binding ? credentialAssertDirectoryAnchor(binding.root, "credential project root") : null;
+    const parent = binding
+      ? credentialAssertDirectoryAnchor(binding.parent, "credential destination directory", root)
+      : credentialDirectoryAnchor(path.dirname(resolvedDestination), "credential destination directory");
+    if (path.dirname(resolvedDestination) !== parent.path || path.basename(resolvedDestination).includes(path.sep)) {
+      throw new Error("credential destination path is not anchored to its managed directory");
+    }
+    const destination = path.join(parent.realpath, path.basename(resolvedDestination));
+    const snapshot = (() => {
+      try {
+        const stat = credentialFileSnapshot(destination, "credential destination");
+        if (!options.force) throw new Error("credential destination already exists (use --force to replace)");
+        return { exists: true, stat };
+      } catch (error) {
+        if (error && error.code === "ENOENT") return { exists: false };
+        throw error;
+      }
+    })();
+    const temp = path.join(parent.realpath, `.${path.basename(destination)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+    let tempStat = null;
+    try {
+      credentialAssertDirectoryAnchor(parent, "credential destination directory", root);
+      fs.copyFileSync(source, temp, fs.constants.COPYFILE_EXCL);
+      tempStat = credentialFileSnapshot(temp, "credential temporary file");
+      if (!tempStat || tempStat.size !== sourceStat.size) {
+        throw new Error("credential copy did not produce the exact regular file");
+      }
+      let readFd;
+      try {
+        readFd = fs.openSync(temp, fs.constants.O_RDONLY | CREDENTIAL_NOFOLLOW);
+        const opened = fs.fstatSync(readFd);
+        if (!credentialSameFileSnapshot(opened, tempStat) || opened.size !== sourceStat.size) {
+          throw new Error("credential temporary file changed while opening");
+        }
+      } finally {
+        if (readFd !== undefined) try { fs.closeSync(readFd); } catch { /* preserve original failure */ }
+      }
+      try { fs.chmodSync(temp, 0o600); } catch { /* Windows/best-effort */ }
+      credentialAssertDirectoryAnchor(parent, "credential destination directory", root);
+      credentialPublishFile(parent, path.basename(destination), { path: temp, stat: tempStat }, snapshot.exists ? snapshot.stat : null);
+    } finally {
+      if (tempStat) credentialRemoveOwnedFile(temp, tempStat);
+    }
+    return destinationPath;
+  } finally {
+    if (binding) credentialDestinationBindings.delete(resolvedDestination);
+  }
+}
+
 module.exports = {
   CREDENTIAL_INDEX_SECTION_CLI,
   localCredentialConfigCli,
@@ -259,4 +604,7 @@ module.exports = {
   readJsonObjectCli,
   upsertLocalCredentialMapCli,
   safeCredentialDestRelCli,
+  credentialProjectRootCli,
+  resolveCredentialDestinationCli,
+  copyCredentialFileAtomicCli,
 };

package/engine/project/env-file.cjs

@@ -8,13 +8,85 @@
  */
 const fs = require("node:fs");
 const path = require("node:path");
+const crypto = require("node:crypto");
+
+const MAX_DOT_ENV_BYTES = 512 * 1024;
+
+function readEnvSnapshot(file) {
+  let before;
+  try {
+    before = fs.lstatSync(file);
+  } catch (error) {
+    if (error && error.code === "ENOENT") return { exists: false, body: "" };
+    throw error;
+  }
+  if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_DOT_ENV_BYTES) {
+    throw new Error("credential env target must be a bounded regular non-symbolic-link file");
+  }
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+  try {
+    const opened = fs.fstatSync(fd);
+    if (
+      !opened.isFile() || opened.size > MAX_DOT_ENV_BYTES ||
+      opened.dev !== before.dev || opened.ino !== before.ino
+    ) throw new Error("credential env target changed while opening");
+    return {
+      exists: true,
+      body: fs.readFileSync(fd, "utf8"),
+      dev: opened.dev,
+      ino: opened.ino,
+      size: opened.size,
+      mtimeMs: opened.mtimeMs,
+      ctimeMs: opened.ctimeMs,
+    };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function assertEnvSnapshotUnchanged(file, snapshot) {
+  let current;
+  try { current = fs.lstatSync(file); }
+  catch (error) {
+    if (error && error.code === "ENOENT" && !snapshot.exists) return;
+    throw new Error("credential env target changed before replacement");
+  }
+  if (
+    !snapshot.exists || !current.isFile() || current.isSymbolicLink() ||
+    current.dev !== snapshot.dev || current.ino !== snapshot.ino ||
+    current.size !== snapshot.size || current.mtimeMs !== snapshot.mtimeMs || current.ctimeMs !== snapshot.ctimeMs
+  ) throw new Error("credential env target changed before replacement");
+}
+
+function replaceEnvFileAtomic(temp, file, snapshot) {
+  assertEnvSnapshotUnchanged(file, snapshot);
+  try {
+    fs.renameSync(temp, file);
+    return;
+  } catch (error) {
+    if (
+      process.platform !== "win32" || !snapshot.exists ||
+      !["EEXIST", "EPERM", "EACCES"].includes(error && error.code)
+    ) throw error;
+  }
+  assertEnvSnapshotUnchanged(file, snapshot);
+  const backup = `${file}.agentlas-${process.pid}-${crypto.randomUUID()}.bak`;
+  fs.renameSync(file, backup);
+  try {
+    fs.renameSync(temp, file);
+  } catch (error) {
+    try { if (!fs.existsSync(file)) fs.renameSync(backup, file); } catch { /* leave the backup recoverable */ }
+    throw error;
+  }
+  try { fs.rmSync(backup, { force: true }); } catch { /* committed target is authoritative */ }
+}
 
 /** .env 파싱 — 값 보존 없이 키만 필요할 때도 같은 파서를 쓴다 (KEY=VALUE, # 주석). */
 function readDotEnvFile(file) {
   const result = {};
   let raw;
   try {
-    raw = fs.readFileSync(file, "utf8");
+    raw = readEnvSnapshot(file).body;
   } catch {
     return result;
   }
@@ -30,17 +102,30 @@ function readDotEnvFile(file) {
 }
 
 function upsertEnvLine(file, key, value) {
-  let body = "";
-  try { body = fs.readFileSync(file, "utf8"); } catch { /* new file */ }
-  const line = `${key}=${value}`;
+  if (!/^[A-Z][A-Z0-9_]*$/.test(String(key || ""))) throw new Error("credential env key must look like ENV_NAME");
+  const text = String(value == null ? "" : value);
+  if (/[\u0000\r\n]/.test(text)) throw new Error("credential env value must be a single line; use `agentlas creds file` for multiline credentials");
+  const snapshot = readEnvSnapshot(file);
+  let body = snapshot.body;
+  const line = `${key}=${text}`;
   const re = new RegExp("^" + key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "=.*$", "m");
-  if (re.test(body)) body = body.replace(re, line);
+  // Replacement strings interpret `$&`, `$1`, and similar tokens. Credentials
+  // are opaque bytes, so use a function replacement and preserve them verbatim.
+  if (re.test(body)) body = body.replace(re, () => line);
   else body = body ? body.replace(/\n?$/, "\n") + line + "\n" : line + "\n";
-  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (Buffer.byteLength(body, "utf8") > MAX_DOT_ENV_BYTES) throw new Error("credential env file exceeds the 512 KiB safety limit");
+  const directory = path.dirname(file);
+  fs.mkdirSync(directory, { recursive: true });
+  const temp = path.join(directory, `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  try {
+    fs.writeFileSync(temp, body, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    replaceEnvFileAtomic(temp, file, snapshot);
+  } finally {
+    try { fs.rmSync(temp, { force: true }); } catch { /* best-effort cleanup */ }
+  }
   // 이 헬퍼의 모든 호출자는 credential 값/경로를 기록한다. 새 파일뿐 아니라 기존 0644
   // 파일도 매번 0600으로 수렴시켜 같은 머신의 다른 계정이 읽지 못하게 한다.
-  fs.writeFileSync(file, body, { encoding: "utf8", mode: 0o600 });
   try { fs.chmodSync(file, 0o600); } catch { /* Windows/읽기전용 FS best-effort */ }
 }
 
-module.exports = { readDotEnvFile, upsertEnvLine };
+module.exports = { MAX_DOT_ENV_BYTES, readDotEnvFile, upsertEnvLine };