@aipermission/mcp 0.2.36 → 0.2.38

package/README.md

@@ -33,7 +33,7 @@ npx -y @aipermission/mcp init \
 
 The init command prompts for your AIPermission API token and writes the MCP client configuration for the selected provider. Generated runtime configs pin the exact package version that wrote them; re-run init when you intentionally upgrade a client.
 
-The generated MCP config contains a bearer token. Keep it private. For project-local configs such as `.mcp.json`, `.cursor/mcp.json`, and `.vscode/mcp.json`, the init command refuses to write into files already tracked by Git unless `--force` is passed. For untracked project-local configs, it adds the file to `.git/info/exclude` when it detects a Git repository. Use `--print` if you prefer to copy the config manually. If a token config is committed or shared, revoke that token in the AIPermission UI.
+The generated MCP config contains a bearer token. Keep it private. For project-local configs such as `.mcp.json`, `.cursor/mcp.json`, and `.vscode/mcp.json`, the init command refuses to write into files already tracked by Git unless `--force` is passed. For untracked project-local configs, it adds both the final file and its crash-safe temporary-file pattern to `.git/info/exclude` before writing. Symbolic-link config destinations are rejected instead of being silently replaced; use `--print` and update a symlink-managed config through its owning tool. If a token config is committed or shared, revoke that token in the AIPermission UI.
 
 ## Manual Config
 
@@ -42,7 +42,7 @@ The generated MCP config contains a bearer token. Keep it private. For project-l
   "mcpServers": {
     "aipermission": {
       "command": "npx",
-      "args": ["-y", "@aipermission/mcp@0.2.36"],
+      "args": ["-y", "@aipermission/mcp@0.2.38"],
       "env": {
         "NODE_ENV": "production",
         "AIPERMISSION_API_URL": "http://localhost:3210",

package/dist/init.js

@@ -8,6 +8,15 @@ import { promisify } from "node:util";
 import { pathToFileURL } from "node:url";
 import { stdin as input, stdout as output } from "node:process";
 import { DEFAULT_API_URL, normalizeLocalAPIURL } from "./local-url.js";
+import {
+  atomicWritePrivateFile,
+  privateLockPath,
+  privateStagingIgnorePath,
+  privateStagingPath,
+  privateTemporaryIgnorePath,
+  privateTemporaryPath,
+  withPrivateFileLock,
+} from "./private-file.js";
 
 const require = createRequire(import.meta.url);
 const execFileAsync = promisify(execFile);
@@ -78,9 +87,7 @@ export async function runInit(argv = []) {
     const provider = flags.provider
       ? findProvider(flags.provider)
       : await selectProvider("Which AI client should use this token?", providers);
-    const name = sanitizeName(
-      flags.name || (await ask(rl, "MCP server name", "aipermission"))
-    );
+    const name = sanitizeName(flags.name || (await ask(rl, "MCP server name", "aipermission")));
     const apiUrl = normalizeURL(flags.apiUrl || DEFAULT_API_URL);
     const token = await resolveToken({ ...flags, stdinToken }, rl);
 
@@ -104,7 +111,9 @@ export async function runInit(argv = []) {
       console.log(`${color.dim}Git:${color.reset} added ${result.gitExcludeEntry} to .git/info/exclude`);
     }
     console.log("");
-    console.log(`${color.yellow}Keep this config private:${color.reset} it contains an AIPermission bearer token. If it is committed, revoke the token.`);
+    console.log(
+      `${color.yellow}Keep this config private:${color.reset} it contains an AIPermission bearer token. If it is committed, revoke the token.`,
+    );
     console.log(`${color.yellow}Restart the AI client so it reloads MCP servers.${color.reset}`);
   } finally {
     rl.close();
@@ -151,9 +160,7 @@ export function parseFlags(argv) {
 
 function findProvider(idOrLabel) {
   const normalized = String(idOrLabel).trim().toLowerCase();
-  const provider = providers.find(
-    (item) => item.id === normalized || item.label.toLowerCase() === normalized
-  );
+  const provider = providers.find((item) => item.id === normalized || item.label.toLowerCase() === normalized);
   if (!provider) {
     throw new Error(`Unknown provider: ${idOrLabel}`);
   }
@@ -175,18 +182,12 @@ async function selectProvider(title, items) {
       output.write(`\x1b[${renderedLines}A`);
       output.write("\x1b[J");
     }
-    const lines = [
-      `${color.bold}${color.cyan}${title}${color.reset}`,
-      `${color.dim}Use ↑/↓ and Enter.${color.reset}`,
-      "",
-    ];
+    const lines = [`${color.bold}${color.cyan}${title}${color.reset}`, `${color.dim}Use ↑/↓ and Enter.${color.reset}`, ""];
     for (let i = 0; i < items.length; i += 1) {
       const selected = i === index;
       const marker = selected ? `${color.green}›${color.reset}` : " ";
       const label = selected ? `${color.bold}${items[i].label}${color.reset}` : items[i].label;
-      lines.push(
-        `${marker} ${label} ${color.dim}- ${items[i].description}${color.reset}`
-      );
+      lines.push(`${marker} ${label} ${color.dim}- ${items[i].description}${color.reset}`);
     }
     output.write("\x1b[?25l");
     output.write(`${lines.join("\n")}\n`);
@@ -210,7 +211,7 @@ async function selectProvider(title, items) {
     };
     const onData = (buffer) => {
       const value = buffer.toString("utf8");
-      const keys = value.match(/\u001b\[[AB]|\r|\n|\u0003|./g) || [];
+      const keys = splitInputKeys(value);
       for (const key of keys) {
         if (key === "\u0003") {
           cleanup();
@@ -313,87 +314,112 @@ export function buildMCPServerConfig({ apiUrl, token }) {
 }
 
 export async function writeProviderConfig(providerID, name, config, options = {}) {
+  const projectRoot = process.cwd();
+  const homeRoot = os.homedir();
   if (providerID === "codex") {
-    const filePath = path.join(os.homedir(), ".codex", "config.toml");
-    await writeCodexConfig(filePath, name, config);
+    const filePath = path.join(homeRoot, ".codex", "config.toml");
+    await writeCodexConfig(filePath, name, config, { trustedRoot: homeRoot });
     return { path: filePath };
   }
   if (providerID === "claude-code") {
-    const filePath = path.join(process.cwd(), ".mcp.json");
+    const filePath = path.join(projectRoot, ".mcp.json");
     await assertProjectConfigWritable(filePath, options);
-    await writeJSONMCPConfig(filePath, name, config, "mcpServers");
-    return { path: filePath, ...(await protectGitIgnoredConfig(filePath)) };
+    const protection = await protectGitIgnoredConfig(filePath);
+    await writeJSONMCPConfig(filePath, name, config, "mcpServers", { trustedRoot: projectRoot });
+    return { path: filePath, ...protection };
   }
   if (providerID === "cursor") {
-    const filePath = path.join(process.cwd(), ".cursor", "mcp.json");
+    const filePath = path.join(projectRoot, ".cursor", "mcp.json");
     await assertProjectConfigWritable(filePath, options);
-    await writeJSONMCPConfig(filePath, name, config, "mcpServers");
-    return { path: filePath, ...(await protectGitIgnoredConfig(filePath)) };
+    const protection = await protectGitIgnoredConfig(filePath);
+    await writeJSONMCPConfig(filePath, name, config, "mcpServers", { trustedRoot: projectRoot });
+    return { path: filePath, ...protection };
   }
   if (providerID === "vscode") {
-    const filePath = path.join(process.cwd(), ".vscode", "mcp.json");
+    const filePath = path.join(projectRoot, ".vscode", "mcp.json");
     await assertProjectConfigWritable(filePath, options);
-    await writeJSONMCPConfig(filePath, name, config, "servers");
-    return { path: filePath, ...(await protectGitIgnoredConfig(filePath)) };
+    const protection = await protectGitIgnoredConfig(filePath);
+    await writeJSONMCPConfig(filePath, name, config, "servers", { trustedRoot: projectRoot });
+    return { path: filePath, ...protection };
   }
   if (providerID === "windsurf") {
-    const filePath = path.join(os.homedir(), ".codeium", "windsurf", "mcp_config.json");
-    await writeJSONMCPConfig(filePath, name, config, "mcpServers");
+    const filePath = path.join(homeRoot, ".codeium", "windsurf", "mcp_config.json");
+    await writeJSONMCPConfig(filePath, name, config, "mcpServers", { trustedRoot: homeRoot });
     return { path: filePath };
   }
   if (providerID === "antigravity") {
-    const filePath = path.join(os.homedir(), ".gemini", "antigravity", "mcp_config.json");
-    await writeJSONMCPConfig(filePath, name, config, "mcpServers");
+    const filePath = path.join(homeRoot, ".gemini", "antigravity", "mcp_config.json");
+    await writeJSONMCPConfig(filePath, name, config, "mcpServers", { trustedRoot: homeRoot });
     return { path: filePath };
   }
   if (providerID === "gemini") {
-    const filePath = path.join(os.homedir(), ".gemini", "settings.json");
-    await writeJSONMCPConfig(filePath, name, config, "mcpServers");
+    const filePath = path.join(homeRoot, ".gemini", "settings.json");
+    await writeJSONMCPConfig(filePath, name, config, "mcpServers", { trustedRoot: homeRoot });
     return { path: filePath };
   }
   throw new Error(`Unsupported provider: ${providerID}`);
 }
 
-export async function writeJSONMCPConfig(filePath, name, config, rootKey) {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  let root = {};
-  try {
-    root = JSON.parse(await fs.readFile(filePath, "utf8"));
-  } catch (error) {
-    if (error.code !== "ENOENT") {
-      throw new Error(`Could not read JSON config at ${filePath}: ${error.message}`);
-    }
-  }
-  if (!root || typeof root !== "object" || Array.isArray(root)) {
-    root = {};
-  }
-  root[rootKey] =
-    root[rootKey] && typeof root[rootKey] === "object" && !Array.isArray(root[rootKey])
-      ? root[rootKey]
-      : {};
-  root[rootKey][name] = config;
-  await writePrivateFile(filePath, `${JSON.stringify(root, null, 2)}\n`);
+export async function writeJSONMCPConfig(filePath, name, config, rootKey, options = {}) {
+  await withPrivateFileLock(
+    filePath,
+    async () => {
+      let root = {};
+      try {
+        root = JSON.parse(await fs.readFile(filePath, "utf8"));
+      } catch (error) {
+        if (error.code !== "ENOENT") {
+          throw new Error(`Could not read JSON config at ${filePath}: ${error.message}`, { cause: error });
+        }
+      }
+      if (!root || typeof root !== "object" || Array.isArray(root)) root = {};
+      const currentServers = root[rootKey];
+      const servers =
+        currentServers && typeof currentServers === "object" && !Array.isArray(currentServers)
+          ? { ...currentServers }
+          : Object.create(null);
+      Object.defineProperty(servers, name, { value: config, enumerable: true, configurable: true, writable: true });
+      root[rootKey] = servers;
+      await writePrivateFile(filePath, `${JSON.stringify(root, null, 2)}\n`, options);
+    },
+    options,
+  );
 }
 
-async function writeCodexConfig(filePath, name, config) {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  let current = "";
-  try {
-    current = await fs.readFile(filePath, "utf8");
-  } catch (error) {
-    if (error.code !== "ENOENT") {
-      throw error;
+function splitInputKeys(value) {
+  const keys = [];
+  for (let index = 0; index < value.length; index += 1) {
+    const sequence = value.slice(index, index + 3);
+    if (sequence === "\u001b[A" || sequence === "\u001b[B") {
+      keys.push(sequence);
+      index += 2;
+      continue;
     }
+    keys.push(value[index]);
   }
+  return keys;
+}
 
-  const next = removeCodexServer(current, name).trimEnd();
-  const block = codexServerBlock(name, config);
-  await writePrivateFile(filePath, `${next ? `${next}\n\n` : ""}${block}\n`);
+async function writeCodexConfig(filePath, name, config, options = {}) {
+  await withPrivateFileLock(
+    filePath,
+    async () => {
+      let current = "";
+      try {
+        current = await fs.readFile(filePath, "utf8");
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+      const next = removeCodexServer(current, name).trimEnd();
+      const block = codexServerBlock(name, config);
+      await writePrivateFile(filePath, `${next ? `${next}\n\n` : ""}${block}\n`, options);
+    },
+    options,
+  );
 }
 
-async function writePrivateFile(filePath, contents) {
-  await fs.writeFile(filePath, contents, { mode: 0o600 });
-  await fs.chmod(filePath, 0o600);
+async function writePrivateFile(filePath, contents, options = {}) {
+  await atomicWritePrivateFile(filePath, contents, options);
 }
 
 async function assertProjectConfigWritable(filePath, options = {}) {
@@ -408,7 +434,7 @@ async function assertProjectConfigWritable(filePath, options = {}) {
     [
       `Refusing to write AIPERMISSION_API_TOKEN into tracked git file: ${tracked}`,
       "Use --print to copy the config manually, untrack/ignore that file, or rerun with --force if you intentionally accept commit risk.",
-    ].join("\n")
+    ].join("\n"),
   );
 }
 
@@ -421,26 +447,52 @@ async function protectGitIgnoredConfig(filePath) {
   if (relativePath.startsWith("../") || path.isAbsolute(relativePath)) {
     return {};
   }
-  const excludePath = path.join(repository.gitDir, "info", "exclude");
-  let current = "";
+  const excludePath = repository.excludePath;
+  const temporaryRelativePath = path.relative(repository.workTree, privateTemporaryIgnorePath(filePath)).split(path.sep).join("/");
+  const stagingRelativePath = path.relative(repository.workTree, privateStagingIgnorePath(filePath)).split(path.sep).join("/");
+  const lockRelativePath = path.relative(repository.workTree, privateLockPath(filePath)).split(path.sep).join("/");
+  const ignoreEntries = [
+    gitIgnoreLiteral(relativePath),
+    gitIgnoreWildcardPath(temporaryRelativePath),
+    gitIgnoreWildcardPath(stagingRelativePath),
+    gitIgnoreLiteral(lockRelativePath),
+  ];
   try {
-    current = await fs.readFile(excludePath, "utf8");
+    await withPrivateFileLock(
+      excludePath,
+      async () => {
+        let current = "";
+        try {
+          current = await fs.readFile(excludePath, "utf8");
+        } catch (error) {
+          if (error.code !== "ENOENT") throw error;
+        }
+        const entries = new Set(current.split(/\r?\n/));
+        const missingEntries = ignoreEntries.filter((entry) => !entries.has(entry));
+        if (missingEntries.length === 0) return;
+        const prefix = current && !current.endsWith("\n") ? "\n" : "";
+        await atomicWritePrivateFile(excludePath, `${current}${prefix}${missingEntries.join("\n")}\n`, {
+          trustedRoot: path.dirname(excludePath),
+        });
+      },
+      { trustedRoot: path.dirname(excludePath) },
+    );
+    await assertGitIgnored(repository, [
+      relativePath,
+      privateTemporaryCheckPath(filePath, repository.workTree),
+      privateStagingCheckPath(filePath, repository.workTree),
+      lockRelativePath,
+    ]);
   } catch (error) {
-    if (error.code !== "ENOENT") {
-      return {};
-    }
-  }
-  const entries = current.split(/\r?\n/).map((line) => line.trim());
-  if (!entries.includes(relativePath)) {
-    const prefix = current && !current.endsWith("\n") ? "\n" : "";
-    try {
-      await fs.mkdir(path.dirname(excludePath), { recursive: true });
-      await fs.appendFile(excludePath, `${prefix}${relativePath}\n`, { mode: 0o600 });
-    } catch {
-      return {};
-    }
+    throw new Error(`Could not protect MCP config with local Git excludes: ${error.message}`, { cause: error });
   }
-  return { gitExcluded: true, gitExcludeEntry: relativePath };
+  return {
+    gitExcluded: true,
+    gitExcludeEntry: relativePath,
+    gitExcludeTemporaryEntry: temporaryRelativePath,
+    gitExcludeStagingEntry: stagingRelativePath,
+    gitExcludeLockEntry: lockRelativePath,
+  };
 }
 
 async function gitTrackedPath(filePath) {
@@ -453,30 +505,87 @@ async function gitTrackedPath(filePath) {
     return "";
   }
   try {
-    await execFileAsync("git", ["-C", repository.workTree, "ls-files", "--error-unmatch", "--", relativePath], { windowsHide: true });
+    await execFileAsync("git", ["-C", repository.workTree, "ls-files", "--error-unmatch", "--", relativePath], {
+      windowsHide: true,
+    });
     return relativePath;
-  } catch {
-    return "";
+  } catch (error) {
+    if (error.code === 1) return "";
+    throw new Error(`Could not verify whether MCP config is tracked by Git: ${gitErrorMessage(error)}`, { cause: error });
   }
 }
 
 async function discoverGitRepository(startDir) {
   try {
-    const { stdout } = await execFileAsync(
-      "git",
-      ["-C", path.resolve(startDir), "rev-parse", "--show-toplevel", "--absolute-git-dir"],
-      { encoding: "utf8", windowsHide: true }
-    );
+    const { stdout } = await execFileAsync("git", ["-C", path.resolve(startDir), "rev-parse", "--show-toplevel", "--absolute-git-dir"], {
+      encoding: "utf8",
+      windowsHide: true,
+    });
     const [workTree, gitDir] = stdout.trim().split(/\r?\n/);
     if (!workTree || !gitDir) {
       return null;
     }
-    return { workTree: path.resolve(workTree), gitDir: path.resolve(gitDir) };
-  } catch {
-    return null;
+    const { stdout: excludeOutput } = await execFileAsync(
+      "git",
+      ["-C", path.resolve(startDir), "rev-parse", "--path-format=absolute", "--git-path", "info/exclude"],
+      { encoding: "utf8", windowsHide: true },
+    );
+    const excludePath = excludeOutput.trim();
+    if (!excludePath) throw new Error("Git did not return an exclude path");
+    return { workTree: path.resolve(workTree), gitDir: path.resolve(gitDir), excludePath: path.resolve(excludePath) };
+  } catch (error) {
+    if (/not a git repository/i.test(`${error.stderr || ""}\n${error.message || ""}`)) return null;
+    throw new Error(`Could not inspect Git repository: ${gitErrorMessage(error)}`, { cause: error });
+  }
+}
+
+async function assertGitIgnored(repository, relativePaths) {
+  for (const relativePath of relativePaths) {
+    try {
+      await execFileAsync("git", ["-C", repository.workTree, "check-ignore", "--no-index", "-q", "--", relativePath], {
+        windowsHide: true,
+      });
+    } catch (error) {
+      if (error.code === 1) {
+        throw new Error(`Git still permits sensitive MCP path: ${relativePath}`, { cause: error });
+      }
+      throw new Error(`Could not verify local Git exclusion: ${gitErrorMessage(error)}`, { cause: error });
+    }
   }
 }
 
+function privateTemporaryCheckPath(filePath, workTree) {
+  return path.relative(workTree, privateTemporaryPath(filePath, "git-check")).split(path.sep).join("/");
+}
+
+function privateStagingCheckPath(filePath, workTree) {
+  return path.relative(workTree, privateStagingPath(filePath, "git-check")).split(path.sep).join("/");
+}
+
+function escapeGitIgnoreFragment(value) {
+  let result = "";
+  for (const character of value) {
+    result += ["\\", "*", "?", "[", "]", "#", "!", " "].includes(character) ? `\\${character}` : character;
+  }
+  return result;
+}
+
+function gitIgnoreLiteral(relativePath) {
+  return `/${escapeGitIgnoreFragment(relativePath)}`;
+}
+
+function gitIgnoreWildcardPath(relativePath) {
+  const wildcardIndex = relativePath.lastIndexOf("*");
+  if (wildcardIndex < 0) throw new Error(`Git ignore wildcard path is missing its generated wildcard: ${relativePath}`);
+  return `/${escapeGitIgnoreFragment(relativePath.slice(0, wildcardIndex))}*${escapeGitIgnoreFragment(
+    relativePath.slice(wildcardIndex + 1),
+  )}`;
+}
+
+function gitErrorMessage(error) {
+  return String(error.stderr || error.message || error).trim();
+}
+
 function removeCodexServer(source, name) {
   const main = `[mcp_servers.${tomlKey(name)}]`;
   const env = `[mcp_servers.${tomlKey(name)}.env]`;
@@ -533,6 +642,9 @@ export function sanitizeName(value) {
   if (!name) {
     throw new Error("MCP server name is required.");
   }
+  if (["__proto__", "prototype", "constructor"].includes(name.toLowerCase())) {
+    throw new Error("MCP server name is reserved.");
+  }
   return name;
 }
 

package/dist/install-skill.js

@@ -79,10 +79,7 @@ export async function loadSkill(source) {
 }
 
 function bundledSkillCandidates() {
-  return [
-    path.join(moduleDir, "resources", SKILL_NAME, "SKILL.md"),
-    path.join(moduleDir, "..", "resources", SKILL_NAME, "SKILL.md"),
-  ];
+  return [path.join(moduleDir, "resources", SKILL_NAME, "SKILL.md"), path.join(moduleDir, "..", "resources", SKILL_NAME, "SKILL.md")];
 }
 
 async function readSkillSource(source) {
@@ -131,10 +128,12 @@ export function renderInstruction(client, skill) {
 }
 
 export function normalizeClient(value) {
-  const client = String(value || "").trim().toLowerCase();
+  const client = String(value || "")
+    .trim()
+    .toLowerCase();
   const aliases = {
     claude: "claude-code",
-    "claude_code": "claude-code",
+    claude_code: "claude-code",
     "claude-code": "claude-code",
     copilot: "vscode",
     "vs-code": "vscode",
@@ -151,16 +150,18 @@ export function normalizeClient(value) {
 }
 
 function clientLabel(client) {
-  return {
-    codex: "Codex",
-    "claude-code": "Claude Code",
-    cursor: "Cursor",
-    vscode: "VS Code / GitHub Copilot",
-    windsurf: "Windsurf",
-    antigravity: "Google Antigravity",
-    gemini: "Gemini CLI",
-    custom: "Custom",
-  }[client] || client;
+  return (
+    {
+      codex: "Codex",
+      "claude-code": "Claude Code",
+      cursor: "Cursor",
+      vscode: "VS Code / GitHub Copilot",
+      windsurf: "Windsurf",
+      antigravity: "Google Antigravity",
+      gemini: "Gemini CLI",
+      custom: "Custom",
+    }[client] || client
+  );
 }
 
 function stripSkillFrontmatter(value) {

package/dist/private-file.js

@@ -0,0 +1,299 @@
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const staleTemporaryAgeMs = 24 * 60 * 60 * 1000;
+const lockRetryDelayMs = 50;
+const lockRetryLimit = 100;
+
+export async function atomicWritePrivateFile(filePath, contents, options = {}) {
+  const destination = path.resolve(filePath);
+  const rename = options.rename || fs.rename;
+  const suffix = options.suffix || `${process.pid}-${randomBytes(8).toString("hex")}`;
+  const directory = path.dirname(destination);
+  let temporaryPath = privateTemporaryPath(destination, suffix);
+  let stagingDirectory;
+  let handle;
+
+  await ensurePrivateDirectory(directory, options);
+  await validatePrivateDestination(destination, options);
+  await cleanupStalePrivateFiles(destination, options);
+  try {
+    if (operatingSystem(options) === "win32") {
+      stagingDirectory = await createPrivateStagingDirectory(destination, options);
+      temporaryPath = path.join(stagingDirectory, path.basename(temporaryPath));
+    }
+    handle = await fs.open(temporaryPath, "wx", 0o600);
+    await enforcePrivateFilePermissions(temporaryPath, options);
+    await handle.writeFile(contents, { encoding: "utf8" });
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await validatePrivateDestination(destination, options);
+    await rename(temporaryPath, destination);
+    await (options.syncDirectory || syncParentDirectory)(directory);
+  } catch (error) {
+    await handle?.close().catch(() => {});
+    await fs.unlink(temporaryPath).catch(() => {});
+    throw error;
+  } finally {
+    if (stagingDirectory) await fs.rm(stagingDirectory, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+export async function withPrivateFileLock(filePath, task, options = {}) {
+  const destination = path.resolve(filePath);
+  const directory = path.dirname(destination);
+  const lockPath = `${destination}.aipermission.lock`;
+  await ensurePrivateDirectory(directory, options);
+  await validatePrivateDestination(destination, options);
+
+  const ownerToken = randomBytes(16).toString("hex");
+  const ownerRecord = JSON.stringify({ pid: process.pid, token: ownerToken });
+  let handle;
+  for (let attempt = 0; attempt < (options.lockRetryLimit ?? lockRetryLimit); attempt += 1) {
+    let createdLock = false;
+    try {
+      handle = await fs.open(lockPath, "wx", 0o600);
+      createdLock = true;
+      await enforcePrivateFilePermissions(lockPath, options);
+      await handle.writeFile(`${ownerRecord}\n`, { encoding: "utf8" });
+      await handle.sync();
+      break;
+    } catch (error) {
+      await handle?.close().catch(() => {});
+      handle = undefined;
+      if (createdLock) await fs.unlink(lockPath).catch(() => {});
+      if (error.code !== "EEXIST") throw error;
+      await delay(options.lockRetryDelayMs ?? lockRetryDelayMs);
+    }
+  }
+  if (!handle) {
+    throw new Error(
+      `Timed out waiting for private config lock: ${destination}. If no other MCP setup process is running, remove ${lockPath} and retry.`,
+    );
+  }
+
+  try {
+    return await task();
+  } finally {
+    await handle.close().catch(() => {});
+    await releaseOwnedLock(lockPath, ownerToken);
+    await (options.syncDirectory || syncParentDirectory)(directory);
+  }
+}
+
+export function privateTemporaryPath(filePath, suffix) {
+  return path.join(path.dirname(filePath), `.${path.basename(filePath)}.aipermission-${suffix}.tmp`);
+}
+
+export function privateTemporaryIgnorePath(filePath) {
+  return privateTemporaryPath(filePath, "*");
+}
+
+export function privateStagingPath(filePath, suffix) {
+  return path.join(path.dirname(filePath), `.${path.basename(filePath)}.aipermission-stage-${suffix}`);
+}
+
+export function privateStagingIgnorePath(filePath) {
+  return privateStagingPath(filePath, "*");
+}
+
+export function privateLockPath(filePath) {
+  return `${filePath}.aipermission.lock`;
+}
+
+export async function cleanupStalePrivateFiles(filePath, options = {}) {
+  const directory = path.dirname(filePath);
+  const prefix = `.${path.basename(filePath)}.aipermission-`;
+  const now = options.now ?? Date.now();
+  const maximumAge = options.staleAgeMs ?? staleTemporaryAgeMs;
+  let entries;
+  try {
+    entries = await fs.readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+  for (const entry of entries) {
+    const temporaryFile = entry.isFile() && entry.name.startsWith(prefix) && entry.name.endsWith(".tmp");
+    const stagingDirectory = entry.isDirectory() && entry.name.startsWith(`${prefix}stage-`);
+    if (!temporaryFile && !stagingDirectory) continue;
+    const temporaryPath = path.join(directory, entry.name);
+    try {
+      const stat = await fs.lstat(temporaryPath);
+      if (now - stat.mtimeMs < maximumAge) continue;
+      if (stat.isFile()) await fs.unlink(temporaryPath);
+      if (stat.isDirectory()) await fs.rm(temporaryPath, { recursive: true, force: true });
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+}
+
+async function ensurePrivateDirectory(directory, options) {
+  const trustedRoot = path.resolve(options.trustedRoot || directory);
+  const resolvedDirectory = path.resolve(directory);
+  assertPathWithinRoot(trustedRoot, resolvedDirectory);
+  const missing = [];
+  const relativeParts = path.relative(trustedRoot, resolvedDirectory).split(path.sep).filter(Boolean);
+  let current = trustedRoot;
+  for (const part of ["", ...relativeParts]) {
+    if (part) current = path.join(current, part);
+    try {
+      const stat = await fs.lstat(current);
+      if (stat.isSymbolicLink()) throw new Error(`Refusing private config path through symbolic link or junction: ${current}`);
+      if (!stat.isDirectory()) throw new Error(`Private config parent is not a directory: ${current}`);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      missing.push(current);
+    }
+  }
+  await fs.mkdir(resolvedDirectory, { recursive: true, mode: 0o700 });
+  await rejectSymbolicPathComponents(trustedRoot, resolvedDirectory);
+  for (const created of missing) {
+    await fs.chmod(created, 0o700).catch((error) => {
+      if (process.platform !== "win32") throw error;
+    });
+    await (options.syncDirectory || syncParentDirectory)(path.dirname(created));
+  }
+}
+
+async function createPrivateStagingDirectory(destination, options) {
+  const prefix = path.join(path.dirname(destination), `.${path.basename(destination)}.aipermission-stage-`);
+  const directory = await (options.makeTemporaryDirectory || fs.mkdtemp)(prefix);
+  try {
+    await enforcePrivateDirectoryPermissions(directory, options);
+    return directory;
+  } catch (error) {
+    await fs.rm(directory, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+async function validatePrivateDestination(filePath, options) {
+  const trustedRoot = path.resolve(options.trustedRoot || path.dirname(filePath));
+  assertPathWithinRoot(trustedRoot, filePath);
+  await rejectSymbolicPathComponents(trustedRoot, path.dirname(filePath));
+  await rejectSymbolicLink(filePath);
+}
+
+async function rejectSymbolicPathComponents(root, directory) {
+  const relativeParts = path.relative(root, directory).split(path.sep).filter(Boolean);
+  let current = root;
+  for (const part of ["", ...relativeParts]) {
+    if (part) current = path.join(current, part);
+    const stat = await fs.lstat(current);
+    if (stat.isSymbolicLink()) {
+      throw new Error(`Refusing private config path through symbolic link or junction: ${current}`);
+    }
+    if (!stat.isDirectory()) {
+      throw new Error(`Private config parent is not a directory: ${current}`);
+    }
+  }
+}
+
+function assertPathWithinRoot(root, destination) {
+  const relative = path.relative(path.resolve(root), path.resolve(destination));
+  if (relative.startsWith(`..${path.sep}`) || relative === ".." || path.isAbsolute(relative)) {
+    throw new Error(`Refusing private config path outside trusted root: ${destination}`);
+  }
+}
+
+async function rejectSymbolicLink(filePath) {
+  try {
+    const stat = await fs.lstat(filePath);
+    if (stat.isSymbolicLink()) {
+      throw new Error(`Refusing to replace symbolic-link config: ${filePath}`);
+    }
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+}
+
+async function releaseOwnedLock(lockPath, ownerToken) {
+  try {
+    const owner = JSON.parse(await fs.readFile(lockPath, "utf8"));
+    if (owner?.token !== ownerToken) return;
+    await fs.unlink(lockPath);
+  } catch (error) {
+    if (error.code === "ENOENT" || error instanceof SyntaxError) return;
+    throw error;
+  }
+}
+
+async function enforcePrivateFilePermissions(filePath, options) {
+  if (options.enforcePermissions) {
+    await options.enforcePermissions(filePath);
+    return;
+  }
+  if (operatingSystem(options) !== "win32") {
+    await fs.chmod(filePath, 0o600);
+    return;
+  }
+  const sid = await currentWindowsSID(options);
+  await runWindowsSystemExecutable("icacls", [filePath, "/inheritance:r", "/grant:r", `*${sid}:(F)`], options);
+}
+
+async function enforcePrivateDirectoryPermissions(directory, options) {
+  if (options.enforceDirectoryPermissions) {
+    await options.enforceDirectoryPermissions(directory);
+    return;
+  }
+  if (operatingSystem(options) !== "win32") {
+    await fs.chmod(directory, 0o700);
+    return;
+  }
+  const sid = await currentWindowsSID(options);
+  await runWindowsSystemExecutable("icacls", [directory, "/inheritance:r", "/grant:r", `*${sid}:(OI)(CI)(F)`], options);
+}
+
+async function currentWindowsSID(options) {
+  const { stdout } = await runWindowsSystemExecutable("whoami", ["/user", "/fo", "csv", "/nh"], options, {
+    encoding: "utf8",
+  });
+  const sid = stdout.match(/S-\d-(?:\d+-)+\d+/)?.[0];
+  if (!sid) throw new Error("Could not determine current Windows SID for private config ACL");
+  return sid;
+}
+
+function runWindowsSystemExecutable(name, args, options, executionOptions = {}) {
+  const execute = options.execFile || execFileAsync;
+  return execute(windowsSystemExecutable(name, options), args, {
+    windowsHide: true,
+    ...executionOptions,
+  });
+}
+
+function windowsSystemExecutable(name, options) {
+  const systemRoot = options.windowsSystemRoot || process.env.SystemRoot || process.env.windir || "C:\\Windows";
+  if (!path.win32.isAbsolute(systemRoot)) {
+    throw new Error("Windows SystemRoot must be an absolute path for private config ACL setup");
+  }
+  return path.win32.join(systemRoot, "System32", `${name}.exe`);
+}
+
+function operatingSystem(options) {
+  return options.platform || process.platform;
+}
+
+async function syncParentDirectory(directory) {
+  let handle;
+  try {
+    handle = await fs.open(directory, "r");
+    await handle.sync();
+  } catch (error) {
+    if (process.platform === "win32" && ["EACCES", "EINVAL", "ENOTSUP", "EPERM"].includes(error.code)) return;
+    throw error;
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/dist/resources/aipermission-operator/SKILL.md

@@ -204,8 +204,11 @@ prefer this sequence:
    type, headers, or existence.
 5. Use `download_object` only for bounded object reads explicitly requested by
    the operator.
-6. Keep `overwrite=false` for `upload_object` and `rename_object` unless the
-   operator explicitly approved replacement.
+6. Keep `overwrite=false` for `upload_object` unless the operator explicitly
+   approved replacement. `rename_object` is intentionally unavailable because
+   S3-compatible APIs do not provide an atomic cross-key move. Keep the source
+   intact after creating a destination; deletion is a separate destructive
+   operator decision and must not be inferred from copy verification.
 7. Treat `delete_object` as destructive and ask for explicit confirmation if
    approval mode does not already provide it.
 8. Use `presign_download` and `presign_upload` only for one exact object key

package/dist/server.js

@@ -30,7 +30,7 @@ server.tool(
   {},
   async () => {
     return jsonToolResult(() => apiGet("/api/mcp/connector-targets"));
-  }
+  },
 );
 
 server.tool(
@@ -44,7 +44,7 @@ server.tool(
       const params = new URLSearchParams({ target_ref });
       return apiGet(`/api/mcp/connector-help?${params.toString()}`);
     });
-  }
+  },
 );
 
 server.tool(
@@ -58,7 +58,7 @@ server.tool(
       const params = new URLSearchParams({ target_ref });
       return apiGet(`/api/mcp/connector-actions?${params.toString()}`);
     });
-  }
+  },
 );
 
 server.tool(
@@ -69,17 +69,24 @@ server.tool(
     action_name: z.string().min(1).describe("Action name from get_connector_actions."),
     input: z.record(z.unknown()).optional().describe("Connector-specific action input."),
     reason: z.string().optional().describe("Why this connector action is needed."),
-    idempotency_key: z.string().min(1).max(128).optional().describe("Caller-stable key that makes retries return the original request without running twice."),
+    idempotency_key: z
+      .string()
+      .min(1)
+      .max(128)
+      .optional()
+      .describe("Caller-stable key that makes retries return the original request without running twice."),
   },
   async ({ target_ref, action_name, input, reason, idempotency_key }) => {
-    return jsonToolResult(() => apiPost("/api/mcp/connector-actions/call", {
-      target_ref,
-      action_name,
-      input: input || {},
-      reason: reason || "",
-      idempotency_key,
-    }));
-  }
+    return jsonToolResult(() =>
+      apiPost("/api/mcp/connector-actions/call", {
+        target_ref,
+        action_name,
+        input: input || {},
+        reason: reason || "",
+        idempotency_key,
+      }),
+    );
+  },
 );
 
 server.tool(
@@ -90,7 +97,7 @@ server.tool(
   },
   async ({ request_id }) => {
     return jsonToolResult(() => apiGet(`/api/mcp/connector-action-requests/${request_id}`));
-  }
+  },
 );
 
 server.tool(
@@ -104,7 +111,7 @@ server.tool(
       const query = params.toString();
       return apiGet(`/api/mcp/vault-items${query ? `?${query}` : ""}`);
     });
-  }
+  },
 );
 
 server.tool(
@@ -112,14 +119,16 @@ server.tool(
   "Run a Vault action under the configured project capability. Prompt waits for local approval; Always executes immediately through the same tracked request path. generate_item input accepts name, secret_type, generator_kind, provider, environment, description, expires_at, expiry_warning_days, tags (string array), usage_notes (array of {location, notes}), and shared_project_ids (integer array). restart_session_with_environment input requires target_ref and items with item_id, source_project_id, and optional replace_existing. Never include raw secret values.",
   callVaultActionSchema,
   async ({ project_ref, action_name, input, reason, idempotency_key }) => {
-    return jsonToolResult(() => apiPost("/api/mcp/vault-actions/call", {
-      project_ref,
-      action_name,
-      input,
-      reason,
-      idempotency_key,
-    }));
-  }
+    return jsonToolResult(() =>
+      apiPost("/api/mcp/vault-actions/call", {
+        project_ref,
+        action_name,
+        input,
+        reason,
+        idempotency_key,
+      }),
+    );
+  },
 );
 
 server.tool(
@@ -128,7 +137,7 @@ server.tool(
   vaultActionRequestSchema,
   async ({ request_id }) => {
     return jsonToolResult(() => apiGet(`/api/mcp/vault-action-requests/${request_id}`));
-  }
+  },
 );
 
 server.tool(
@@ -137,7 +146,7 @@ server.tool(
   vaultActionRequestSchema,
   async ({ request_id }) => {
     return jsonToolResult(() => apiPost(`/api/mcp/vault-action-requests/${request_id}/cancel`, {}));
-  }
+  },
 );
 
 const transport = new StdioServerTransport();
@@ -190,7 +199,7 @@ async function apiFetch(path, options) {
     });
   } catch (error) {
     if (error?.name === "AbortError") {
-      throw new Error(`AIPermission API request timed out after ${timeout}ms`);
+      throw new Error(`AIPermission API request timed out after ${timeout}ms`, { cause: error });
     }
     throw error;
   } finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipermission/mcp",
-  "version": "0.2.36",
+  "version": "0.2.38",
   "mcpName": "io.github.aipermission/aipermission-mcp",
   "description": "Local-first MCP bridge for the aipermission gateway.",
   "license": "AGPL-3.0-only",
@@ -28,6 +28,9 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
+    "format": "prettier --write \"src/**/*.js\" \"test/**/*.js\" \"scripts/**/*.js\"",
+    "format:check": "prettier --check \"src/**/*.js\" \"test/**/*.js\" \"scripts/**/*.js\"",
+    "lint": "eslint src test scripts",
     "prepack": "npm run build",
     "test": "node --test test/*.test.js",
     "start": "node dist/cli.js",
@@ -36,8 +39,21 @@
   "engines": {
     "node": ">=20"
   },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=20.19.0",
+      "onFail": "error"
+    }
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
     "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.9.1",
+    "globals": "^17.11.0",
+    "prettier": "^3.9.6"
   }
 }

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.aipermission/aipermission-mcp",
   "title": "AIPermission",
   "description": "Local-first MCP bridge for the AIPermission gateway.",
-  "version": "0.2.36",
+  "version": "0.2.38",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@aipermission/mcp",
-      "version": "0.2.36",
+      "version": "0.2.38",
       "transport": {
         "type": "stdio"
       }