aimakeall-mcp 0.12.0 → 0.14.0

package/lib/auto-update.mjs

@@ -0,0 +1,407 @@
+// Startup only: no credentials, remote code URLs, or API overrides are accepted.
+import https from "node:https";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
+import { promises as fs, constants } from "node:fs";
+import { gunzipSync } from "node:zlib";
+import { spawn } from "node:child_process";
+
+export const RELEASE_URL = "https://aimakeall.com/api/mcp/release";
+export const LAUNCHER_PROTOCOL = 1;
+export const MIN_NODE_MAJOR = 20;
+export const STARTUP_BUDGET_MS = 25_000;
+export const MAX_ARCHIVE_BYTES = 50 * 1024 * 1024;
+const MAX_EXPANDED_BYTES = 256 * 1024 * 1024;
+const MAX_METADATA_BYTES = 16 * 1024;
+const PACKAGE_NAME = "aimakeall-mcp";
+const packageRoot = fileURLToPath(new URL("../", import.meta.url));
+const VERSION_PATTERN = /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/;
+const CACHE_NAME_PATTERN = /^v((?:0|[1-9]\d{0,8})\.(?:0|[1-9]\d{0,8})\.(?:0|[1-9]\d{0,8}))-([a-f0-9]{32})$/;
+
+function fail(code) { const error = new Error(code); error.code = code; throw error; }
+function remaining(deadline, cap = STARTUP_BUDGET_MS) {
+  const left = deadline - Date.now();
+  if (left <= 0) fail("startup-timeout");
+  return Math.max(1, Math.min(left, cap));
+}
+function exactKeys(value, keys) {
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).sort().join(",") !== [...keys].sort().join(",")) fail("invalid-metadata");
+}
+export function compareVersions(left, right) {
+  if (!VERSION_PATTERN.test(left) || !VERSION_PATTERN.test(right)) fail("invalid-version");
+  const a = left.split(".").map(Number), b = right.split(".").map(Number);
+  for (let index = 0; index < 3; index++) if (a[index] !== b[index]) return Math.sign(a[index] - b[index]);
+  return 0;
+}
+export function validateManifest(value, nodeMajor = Number(process.versions.node.split(".")[0])) {
+  exactKeys(value, ["schemaVersion", "channel", "packageName", "version", "launcherProtocol", "minNodeMajor", "tarballUrl", "integrity", "sizeBytes"]);
+  if (value.schemaVersion !== 1 || value.channel !== "stable" || value.packageName !== PACKAGE_NAME
+    || typeof value.version !== "string" || !VERSION_PATTERN.test(value.version)
+    || value.launcherProtocol !== LAUNCHER_PROTOCOL
+    || !Number.isInteger(value.minNodeMajor) || value.minNodeMajor < MIN_NODE_MAJOR || value.minNodeMajor > 100 || value.minNodeMajor > nodeMajor
+    || !Number.isInteger(value.sizeBytes) || value.sizeBytes < 1 || value.sizeBytes > MAX_ARCHIVE_BYTES
+    || value.tarballUrl !== `https://registry.npmjs.org/aimakeall-mcp/-/aimakeall-mcp-${value.version}.tgz`
+    || typeof value.integrity !== "string" || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(value.integrity)) fail("invalid-manifest");
+  const digest = Buffer.from(value.integrity.slice(7), "base64");
+  if (digest.length !== 64 || digest.toString("base64") !== value.integrity.slice(7)) fail("invalid-integrity");
+  return Object.freeze({ ...value });
+}
+
+// Direct HTTPS: no Authorization, cookies, proxy/API overrides, redirects,
+// or ambient NODE_TLS_REJECT_UNAUTHORIZED trust.
+export function requestBytes(url, { maxBytes, timeoutMs, request = https.get } = {}) {
+  if (url !== RELEASE_URL && !/^https:\/\/registry\.npmjs\.org\/aimakeall-mcp\/-\/aimakeall-mcp-(?:0|[1-9]\d{0,8})\.(?:0|[1-9]\d{0,8})\.(?:0|[1-9]\d{0,8})\.tgz$/.test(url)) fail("untrusted-url");
+  return new Promise((resolve, reject) => {
+    let settled = false, req, response;
+    const finish = (error, data) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error) { response?.destroy(); req?.destroy(); reject(error); }
+      else resolve(data);
+    };
+    const timer = setTimeout(() => finish(new Error("network-timeout")), timeoutMs);
+    try {
+      req = request(url, { rejectUnauthorized: true, headers: { Accept: url === RELEASE_URL ? "application/json" : "application/octet-stream" }, agent: false }, (res) => {
+        response = res;
+        if (res.statusCode !== 200) return finish(new Error(res.statusCode === 503 ? "no-approved-release" : "http-status"));
+        if (res.headers["content-encoding"] && res.headers["content-encoding"] !== "identity") return finish(new Error("unexpected-encoding"));
+        const length = res.headers["content-length"];
+        if (length !== undefined && (!/^\d+$/.test(String(length)) || Number(length) > maxBytes)) return finish(new Error("response-too-large"));
+        let size = 0;
+        const chunks = [];
+        res.on("data", (chunk) => {
+          size += chunk.length;
+          if (size > maxBytes) return finish(new Error("response-too-large"));
+          chunks.push(chunk);
+        });
+        res.on("error", (error) => finish(error));
+        res.on("aborted", () => finish(new Error("response-aborted")));
+        res.on("end", () => finish(null, Buffer.concat(chunks)));
+      });
+      req.on("error", (error) => finish(error));
+    } catch (error) { finish(error); }
+  });
+}
+export function verifyArchive(bytes, manifest) {
+  if (bytes.length !== manifest.sizeBytes) fail("size-mismatch");
+  const actual = createHash("sha512").update(bytes).digest();
+  const expected = Buffer.from(manifest.integrity.slice(7), "base64");
+  if (expected.length !== actual.length || !timingSafeEqual(actual, expected)) fail("integrity-mismatch");
+}
+function safeArchivePath(name) {
+  const parts = name.replace(/\/$/, "").split("/");
+  if (!name.startsWith("package/") || /[\\\x00-\x1f\x7f<>:"|?*]/.test(name)
+    || parts.some((part) => !part || part === ".." || part === "." || /[.\s]$/.test(part)
+      || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))) fail("unsafe-archive-path");
+}
+function parsePax(bytes) {
+  let cursor = 0;
+  const fields = Object.create(null);
+  while (cursor < bytes.length) {
+    const space = bytes.indexOf(32, cursor);
+    if (space < 0) fail("invalid-tar");
+    const lengthText = bytes.subarray(cursor, space).toString();
+    if (!/^[1-9]\d*$/.test(lengthText)) fail("invalid-tar");
+    const length = Number(lengthText);
+    if (!Number.isSafeInteger(length) || length <= space - cursor + 1 || cursor + length > bytes.length) fail("invalid-tar");
+    const record = bytes.subarray(space + 1, cursor + length).toString("utf8");
+    const equals = record.indexOf("=");
+    if (equals < 1 || !record.endsWith("\n")) fail("invalid-tar");
+    const key = record.slice(0, equals);
+    if (!["path", "mtime", "atime", "ctime", "uid", "gid", "uname", "gname"].includes(key) || key in fields) fail("unsafe-archive-entry");
+    fields[key] = record.slice(equals + 1, -1);
+    cursor += length;
+  }
+  return fields;
+}
+// Reject traversal and all link entries before an approved archive is installed.
+export function validateTarball(bytes) {
+  const tar = gunzipSync(bytes, { maxOutputLength: MAX_EXPANDED_BYTES });
+  let offset = 0, count = 0, pending = {};
+  const paths = new Map();
+  function claimPath(name, directory) {
+    safeArchivePath(name);
+    if (name.endsWith("/") && !directory) fail("unsafe-archive-path");
+    const parts = name.replace(/\/$/, "").split("/");
+    for (let index = 0; index < parts.length; index++) {
+      const actual = parts.slice(0, index + 1).join("/");
+      const key = actual.normalize("NFC").toLowerCase();
+      const isDirectory = index < parts.length - 1 || directory;
+      const previous = paths.get(key);
+      if (previous && (previous.actual !== actual || !previous.directory || !isDirectory)) fail("duplicate-archive-path");
+      paths.set(key, { actual, directory: isDirectory });
+    }
+  }
+  while (offset + 512 <= tar.length) {
+    const header = tar.subarray(offset, offset + 512);
+    if (header.every((byte) => byte === 0)) {
+      if (!tar.subarray(offset).every((byte) => byte === 0) || count === 0) fail("invalid-tar");
+      return;
+    }
+    const field = (start, length) => header.subarray(start, start + length).toString("utf8").split("\0")[0];
+    const sizeText = field(124, 12).trim(), checksumText = field(148, 8).trim();
+    if (!/^[0-7]+$/.test(sizeText) || !/^[0-7]+$/.test(checksumText)) fail("invalid-tar");
+    const size = parseInt(sizeText, 8);
+    const checksum = header.reduce((sum, byte, index) => sum + (index >= 148 && index < 156 ? 32 : byte), 0);
+    if (parseInt(checksumText, 8) !== checksum || size > MAX_EXPANDED_BYTES || offset + 512 + size > tar.length) fail("invalid-tar");
+    const type = field(156, 1), prefix = field(345, 155);
+    const name = prefix ? `${prefix}/${field(0, 100)}` : field(0, 100);
+    if (type === "x") {
+      pending = parsePax(tar.subarray(offset + 512, offset + 512 + size));
+      if ("linkpath" in pending || "size" in pending) fail("unsafe-archive-entry");
+      if (pending.path) safeArchivePath(pending.path);
+    } else {
+      if (!["", "0", "5"].includes(type) || field(157, 100)) fail("unsafe-archive-entry");
+      claimPath(pending.path || name, type === "5");
+      if (type === "5" && size !== 0) fail("invalid-tar");
+      pending = {};
+      if (++count > 50_000) fail("archive-too-many-files");
+    }
+    offset += 512 + Math.ceil(size / 512) * 512;
+  }
+  fail("invalid-tar");
+}
+
+async function safeDirectory(directory, { create = false, privateDirectory = false } = {}) {
+  const absolute = path.resolve(directory);
+  const parts = absolute.slice(path.parse(absolute).root.length).split(path.sep).filter(Boolean);
+  let cursor = path.parse(absolute).root;
+  let protectedByPrivateAncestor = false;
+  for (const part of parts) {
+    cursor = path.join(cursor, part);
+    if (create) {
+      try { await fs.mkdir(cursor, { mode: 0o700 }); } catch (error) { if (error.code !== "EEXIST") throw error; }
+    }
+    const stat = await fs.lstat(cursor);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) fail("unsafe-cache-directory");
+    // Another account must not be able to replace the private boundary. Once
+    // beneath a current-user-only directory, npm's ordinary 0775 directories
+    // (Linux umask 0002) are inaccessible to that account and safe. Continue
+    // rejecting symlinks at every level, regardless of the boundary.
+    if (process.platform !== "win32") {
+      if (!protectedByPrivateAncestor && (stat.mode & 0o022) !== 0
+        && !((stat.mode & 0o1000) !== 0 && stat.uid === 0)) fail("unsafe-cache-parent");
+      if (typeof process.getuid === "function" && stat.uid === process.getuid() && (stat.mode & 0o077) === 0)
+        protectedByPrivateAncestor = true;
+    }
+  }
+  const stat = await fs.lstat(absolute);
+  if (privateDirectory && process.platform !== "win32"
+    && ((stat.mode & 0o077) !== 0 || (typeof process.getuid === "function" && stat.uid !== process.getuid()))) fail("unsafe-cache-permissions");
+  return absolute;
+}
+async function readRegular(filename, limit) {
+  const stat = await fs.lstat(filename);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > limit) fail("unsafe-cache-file");
+  const handle = await fs.open(filename, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+  try {
+    const actual = await handle.stat();
+    if (!actual.isFile() || actual.nlink !== 1 || actual.size > limit) fail("unsafe-cache-file");
+    const bytes = await handle.readFile();
+    if (bytes.length > limit) fail("unsafe-cache-file");
+    return bytes;
+  } finally { await handle.close(); }
+}
+async function readJson(filename) { return JSON.parse((await readRegular(filename, MAX_METADATA_BYTES)).toString("utf8")); }
+export async function hashTree(directory, deadline = Infinity) {
+  const hash = createHash("sha512");
+  let total = 0, count = 0;
+  async function walk(current, relative) {
+    remaining(deadline);
+    const stat = await fs.lstat(current);
+    if (stat.isSymbolicLink()) fail("unsafe-cache-symlink");
+    if (stat.isDirectory()) {
+      hash.update(`d:${relative}\0`);
+      for (const name of (await fs.readdir(current)).sort()) await walk(path.join(current, name), relative ? `${relative}/${name}` : name);
+    } else if (stat.isFile() && stat.nlink === 1) {
+      total += stat.size;
+      if (++count > 50_000 || total > MAX_EXPANDED_BYTES) fail("cache-too-large");
+      hash.update(`f:${relative}:${stat.size}\0`);
+      hash.update(await readRegular(current, MAX_EXPANDED_BYTES));
+    } else fail("unsafe-cache-file");
+  }
+  await walk(directory, "");
+  return hash.digest("hex");
+}
+export function cacheName(manifest) {
+  return `v${manifest.version}-${Buffer.from(manifest.integrity.slice(7), "base64").toString("hex").slice(0, 32)}`;
+}
+function runtimeAt(directory) { return path.join(directory, "install", "node_modules", PACKAGE_NAME, "runtime.mjs"); }
+async function verifyCached(root, name, deadline = Infinity) {
+  remaining(deadline);
+  if (!CACHE_NAME_PATTERN.test(name)) fail("invalid-cache-name");
+  const directory = await safeDirectory(path.join(root, name), { privateDirectory: true });
+  const receipt = await readJson(path.join(directory, "receipt.json"));
+  exactKeys(receipt, ["schemaVersion", "manifest", "treeHash"]);
+  const manifest = validateManifest(receipt.manifest);
+  if (receipt.schemaVersion !== 1 || cacheName(manifest) !== name || !/^[a-f0-9]{128}$/.test(receipt.treeHash)) fail("invalid-cache-receipt");
+  verifyArchive(await readRegular(path.join(directory, "release.tgz"), MAX_ARCHIVE_BYTES), manifest);
+  const install = await safeDirectory(path.join(directory, "install"));
+  if (await hashTree(install, deadline) !== receipt.treeHash) fail("cache-tree-mismatch");
+  const runtime = runtimeAt(directory);
+  const metadata = await readJson(path.join(path.dirname(runtime), "package.json"));
+  if (metadata.name !== PACKAGE_NAME || metadata.version !== manifest.version) fail("cache-package-mismatch");
+  await readRegular(runtime, MAX_METADATA_BYTES * 16);
+  return { runtime, version: manifest.version, source: "cache", name };
+}
+
+// Never pass PATs, provider keys, npm tokens/config, NODE_OPTIONS, or the user's
+// output/state configuration to install/check processes.
+export function subprocessEnv(env = process.env) {
+  const clean = {};
+  for (const name of ["PATH", "Path", "SystemRoot", "SYSTEMROOT", "WINDIR", "TEMP", "TMP", "TMPDIR", "LANG", "LC_ALL"])
+    if (typeof env[name] === "string") clean[name] = env[name];
+  clean.AIMAKEALL_MCP_AUTO_UPDATE = "0";
+  return clean;
+}
+export async function findNpmCli(nodeExecutable = process.execPath) {
+  const parent = path.dirname(nodeExecutable);
+  const candidates = [path.join(parent, "node_modules/npm/bin/npm-cli.js"), path.resolve(parent, "../lib/node_modules/npm/bin/npm-cli.js")];
+  for (const candidate of candidates) {
+    try { if ((await fs.stat(candidate)).isFile()) return await fs.realpath(candidate); } catch { /* next layout */ }
+  }
+  fail("npm-cli-unavailable");
+}
+export function npmInstallArgs(npmCli, archive, install, work) {
+  return [npmCli, "install", "--prefix", install, "--offline", "--ignore-scripts", "--no-audit", "--no-fund", "--no-package-lock", "--no-bin-links", "--omit=dev", "--workspaces=false", "--update-notifier=false", "--cache", path.join(work, "npm-cache"), "--userconfig", path.join(work, "empty-npmrc"), "--globalconfig", path.join(work, "empty-global-npmrc"), archive];
+}
+export function runSubprocess(executable, args, { cwd, env, timeoutMs, capture = false, spawnImpl = spawn }) {
+  return new Promise((resolve, reject) => {
+    let child, done = false, output = "";
+    const finish = (error) => { if (done) return; done = true; clearTimeout(timer); error ? reject(error) : resolve(output); };
+    const timer = setTimeout(() => { child?.kill("SIGKILL"); finish(new Error("subprocess-timeout")); }, timeoutMs);
+    try {
+      child = spawnImpl(executable, args, { cwd, env, shell: false, stdio: ["ignore", capture ? "pipe" : "ignore", "ignore"], windowsHide: true });
+      if (capture) child.stdout.on("data", (chunk) => {
+        output += chunk.toString("utf8");
+        if (Buffer.byteLength(output) > 4096) { child.kill("SIGKILL"); finish(new Error("self-check-output-limit")); }
+      });
+      child.once("error", () => finish(new Error("subprocess-error")));
+      child.once("close", (code, signal) => finish(code === 0 && !signal ? null : new Error("subprocess-failed")));
+    } catch { finish(new Error("subprocess-error")); }
+  });
+}
+async function installArchive(stage, manifest, { env, npmCli, run = runSubprocess, deadline = Infinity } = {}) {
+  remaining(deadline);
+  const install = path.join(stage, "install"), work = path.join(stage, "work");
+  await fs.mkdir(install, { mode: 0o700 });
+  await fs.mkdir(work, { mode: 0o700 });
+  await fs.writeFile(path.join(install, "package.json"), JSON.stringify({ private: true, name: "aimakeall-runtime-install", version: "1.0.0" }), { mode: 0o600, flag: "wx" });
+  await fs.writeFile(path.join(work, "empty-npmrc"), "", { mode: 0o600, flag: "wx" });
+  await fs.writeFile(path.join(work, "empty-global-npmrc"), "", { mode: 0o600, flag: "wx" });
+  const clean = subprocessEnv(env);
+  // Explicit empty npm config files and a private cache isolate npm without
+  // changing HOME/USERPROFILE or consulting any user npm configuration.
+  await run(process.execPath, npmInstallArgs(npmCli || await findNpmCli(), path.join(stage, "release.tgz"), install, work), { cwd: work, env: clean, timeoutMs: remaining(deadline, 12_000) });
+  const runtime = runtimeAt(stage);
+  await safeDirectory(path.dirname(runtime));
+  const metadata = await readJson(path.join(path.dirname(runtime), "package.json"));
+  if (metadata.name !== PACKAGE_NAME || metadata.version !== manifest.version) fail("installed-package-mismatch");
+  const treeHash = await hashTree(install, deadline); // Reject links before execution.
+  const check = JSON.parse(await run(process.execPath, [runtime, "--self-check"], { cwd: work, env: clean, timeoutMs: remaining(deadline, 5000), capture: true }));
+  exactKeys(check, ["ok", "version"]);
+  if (check.ok !== true || check.version !== manifest.version) fail("self-check-failed");
+  if (await hashTree(install, deadline) !== treeHash) fail("self-check-modified-runtime");
+  return treeHash;
+}
+async function promote(root, manifest, bytes, previous, options) {
+  remaining(options.deadline);
+  const stage = await fs.mkdtemp(path.join(root, ".staging-"));
+  const name = cacheName(manifest), target = path.join(root, name);
+  try {
+    await fs.writeFile(path.join(stage, "release.tgz"), bytes, { mode: 0o600, flag: "wx" });
+    const treeHash = await installArchive(stage, manifest, options);
+    remaining(options.deadline);
+    await fs.writeFile(path.join(stage, "receipt.json"), JSON.stringify({ schemaVersion: 1, manifest, treeHash }), { mode: 0o600, flag: "wx" });
+    try { await fs.rename(stage, target); }
+    catch (error) {
+      // Concurrent installs never overwrite immutable versions.
+      if (!["EEXIST", "ENOTEMPTY", "EPERM"].includes(error.code)) throw error;
+      await verifyCached(root, name, options.deadline);
+    }
+    const selected = await verifyCached(root, name, options.deadline);
+    remaining(options.deadline);
+    await writePointer(root, name, previous?.name || null);
+    return selected;
+  } finally {
+    // Only our unpublished staging path; never a cached/running version.
+    // Antivirus/file locks may delay deletion on Windows. Cleanup is best
+    // effort and cannot postpone the already-decided runtime handoff.
+    void Promise.resolve().then(() => options.cleanupStaging
+      ? options.cleanupStaging(stage)
+      : fs.rm(stage, { recursive: true, force: true })).catch(() => {});
+  }
+}
+async function writePointer(root, current, previous) {
+  const pointerTemp = path.join(root, `.pointer-${randomUUID()}.json`);
+  await fs.writeFile(pointerTemp, JSON.stringify({ schemaVersion: 1, current, previous }), { mode: 0o600, flag: "wx" });
+  try { await fs.rename(pointerTemp, path.join(root, "current.json")); }
+  finally { void fs.rm(pointerTemp, { force: true }).catch(() => {}); }
+}
+async function cachedRuntimes(root, bundledVersion, deadline) {
+  try {
+    await safeDirectory(root, { privateDirectory: true });
+    try {
+      const pointer = await readJson(path.join(root, "current.json"));
+      exactKeys(pointer, ["schemaVersion", "current", "previous"]);
+      if (pointer.schemaVersion !== 1 || [pointer.current, pointer.previous].some((name) => name !== null && (typeof name !== "string" || !CACHE_NAME_PATTERN.test(name)))) fail("invalid-cache-pointer");
+      // A null current records an explicit official rollback to the bundle.
+      if (pointer.current === null) return null;
+      for (const name of [pointer.current, pointer.previous].filter(Boolean)) {
+        if (compareVersions(CACHE_NAME_PATTERN.exec(name)[1], bundledVersion) < 0) continue;
+        try { return await verifyCached(root, name, deadline); } catch { /* previous */ }
+      }
+    } catch { /* Reject invalid paths/metadata; discover verified versions. */ }
+    const names = (await fs.readdir(root)).filter((name) => CACHE_NAME_PATTERN.test(name));
+    // Recover a checked immutable version after a crashed pointer write.
+    names.sort((a, b) => compareVersions(CACHE_NAME_PATTERN.exec(b)[1], CACHE_NAME_PATTERN.exec(a)[1]));
+    for (const name of names.slice(0, 50)) {
+      remaining(deadline);
+      if (compareVersions(CACHE_NAME_PATTERN.exec(name)[1], bundledVersion) < 0) continue;
+      try { return await verifyCached(root, name, deadline); } catch { /* skip corrupt version */ }
+    }
+  } catch { /* Missing/unsafe cache: bundled fallback. */ }
+  return null;
+}
+
+export async function selectRuntime({ root = path.join(os.homedir(), ".aimakeall", "mcp-runtime"), bundledRoot = packageRoot, env = process.env, download = requestBytes, installOptions = {}, checkOnly = false, startupTimeoutMs = STARTUP_BUDGET_MS } = {}) {
+  const deadline = Date.now() + Math.min(STARTUP_BUDGET_MS, Math.max(1, startupTimeoutMs));
+  const metadata = await readJson(path.join(bundledRoot, "package.json"));
+  if (metadata.name !== PACKAGE_NAME || !VERSION_PATTERN.test(metadata.version)) fail("invalid-bundled-package");
+  const bundled = { runtime: path.join(bundledRoot, "runtime.mjs"), version: metadata.version, source: "bundled", name: null };
+  const cached = await cachedRuntimes(root, metadata.version, deadline);
+  const fallback = cached || bundled;
+  if (env.AIMAKEALL_MCP_AUTO_UPDATE === "0") return { ...fallback, status: "disabled" };
+  try {
+    const manifest = validateManifest(JSON.parse((await download(RELEASE_URL, { maxBytes: MAX_METADATA_BYTES, timeoutMs: remaining(deadline, 2500) })).toString("utf8")));
+    remaining(deadline);
+    if (manifest.version === fallback.version && (fallback.source === "bundled" || fallback.name === cacheName(manifest))) return { ...fallback, status: "up-to-date", availableVersion: manifest.version };
+    if (compareVersions(manifest.version, bundled.version) < 0) return { ...fallback, status: "unsupported-release", availableVersion: manifest.version };
+    if (checkOnly) return { ...fallback, status: "update-available", availableVersion: manifest.version };
+    await safeDirectory(root, { create: true, privateDirectory: true });
+    if (manifest.version === bundled.version) {
+      await writePointer(root, null, cached?.name || null);
+      return { ...bundled, status: "rolled-back", availableVersion: manifest.version };
+    }
+    try {
+      const existing = await verifyCached(root, cacheName(manifest), deadline);
+      remaining(deadline);
+      await writePointer(root, existing.name, cached?.name || null);
+      return { ...existing, status: "updated", availableVersion: manifest.version };
+    } catch { /* Approved release is not yet installed/valid. */ }
+    const bytes = await download(manifest.tarballUrl, { maxBytes: manifest.sizeBytes, timeoutMs: remaining(deadline, 8000) });
+    remaining(deadline);
+    verifyArchive(bytes, manifest);
+    validateTarball(bytes);
+    remaining(deadline);
+    const selected = await promote(root, manifest, bytes, cached, { env, ...installOptions, deadline });
+    return { ...selected, status: "updated", availableVersion: manifest.version };
+  } catch (error) {
+    // Never print raw exception bodies, paths, request URLs, or environment.
+    return { ...fallback, status: error.message === "no-approved-release" ? "no-approved-release" : "update-unavailable" };
+  }
+}

package/lib/cloud-tools.mjs

@@ -27,6 +27,7 @@ import { fetchGenerationJob, GENERATION_JOB_PATH, submitGenerationJob } from "./
 import { loudnessDbfsFromWav, silenceRatioFromWav } from "./wav-dsp.mjs";
 import { trimWavToSeconds } from "./wav-trim.mjs";
 import { registerComposerTools } from "./composer-tools.mjs";
+import { registerReviewTools } from "./review-tools.mjs";
 import { productionFields, visualProductionFields, sceneVisual, composerTextStyle, composerOverlay } from "./production-schemas.mjs";
 import { saveProductionContext, readProductionContext, durationReview, reviewProductionPayload } from "./production-context.mjs";
 import { TTS_PROVIDERS, buildTtsRequestBody, estimateTtsSubtitleLines, requestTtsBinary, resolveTtsSelection } from "./tts-workflow.mjs";
@@ -38,6 +39,11 @@ const BODY_BUDGET_BYTES = SERVER_JSON_BODY_LIMIT_BYTES - 512 * 1024; // 바디
 
 // 컴패니언 계약 상수 — companion/index.cjs 의 MAX_SHOT_COUNT 와 맞춘다.
 const COMPANION_MAX_SHOTS = 18;
+const ttsFallbackFields = {
+  allowProviderFallback: z.boolean().optional().describe("확정된 일시 거절 때만 대체 공급자 허용. 처리 결과 불명·인증·정책 오류는 재합성하지 않음"),
+  fallbackVoices: z.object(Object.fromEntries(TTS_PROVIDERS.map((provider) => [provider,
+    z.object({ voiceId: z.string().min(1) }).optional()]))).optional().describe("선택한 목소리를 대신해도 되는 공급자별 보이스 ID. 미지정이면 명시 보이스를 다른 목소리로 변경하지 않음"),
+};
 
 function assertEncodedBudget(filePaths, { context = "요청" } = {}) {
   let total = 0;
@@ -147,13 +153,21 @@ function describeLocalError(error) {
 }
 
 export function wrapCloudHandler(config, handler) {
-  return async (args) => {
+  return async (args, extra) => {
     if (!config.pat) return textResult(NO_PAT_GUIDE, { isError: true });
     try {
-      return await handler(args);
+      return await handler(args, extra);
     } catch (error) {
       if (error instanceof AimakeallApiError) {
         const retry = error.retryAfterSeconds ? ` (${error.retryAfterSeconds}초 후 재시도)` : "";
+        if (error.partialProviderUsage || error.accountCostEvents.length || error.fallbackStatus) {
+          return textResult(JSON.stringify({ error: error.message, code: error.errorCode, status: error.status,
+            provider: error.provider, fallbackStatus: error.fallbackStatus, fallbackReason: error.fallbackReason,
+            fallbackAvailable: error.fallbackAvailable, capability: error.capability,
+            accountCostEvents: error.accountCostEvents, acceptedTaskCosts: error.acceptedTaskCosts,
+            partialProviderUsage: error.partialProviderUsage, usage: error.usage,
+            guidance: "접수된 비용과 실패 사유를 확인하세요. 결과 불명 작업이나 지정한 보이스를 자동 재생성/교체하지 마세요." }, null, 2), { isError: true });
+        }
         return textResult(`${error.message}${retry}`, { isError: true });
       }
       return textResult(`요청 실패: ${describeLocalError(error)}`, { isError: true });
@@ -187,6 +201,7 @@ function trimAnalysis(analysis) {
 
 export function registerCloudTools(server, config, api) {
   registerComposerTools(server, config, api);
+  registerReviewTools(server, config, api, { wrap: handler => wrapCloudHandler(config, handler) });
   async function completedGenerationResult(job, includePreview) {
     const payload = job.result || {};
     const resultBody = { generationJobId: job.id, status: job.status, kind: job.kind,
@@ -293,7 +308,7 @@ export function registerCloudTools(server, config, api) {
       ttsChars: z.number().int().min(0).max(20000).optional().describe("내레이션 글자 수"),
     },
     wrapCloudHandler(config, async (input) => {
-      if (input.ttsChars > 0) input = { ...input, ttsProvider: (await resolveTtsSelection(api, config, { provider: input.ttsProvider })).provider };
+      if (input.ttsChars > 0) input = { ...input, ttsProvider: (await resolveTtsSelection(api, config, { provider: input.ttsProvider, validateCredentials: false })).provider };
       const payload = await api.request("/api/tracker/cost/estimate", { body: input, method: "POST", timeoutMs: 30_000 });
       return jsonResult(payload);
     }),
@@ -711,17 +726,18 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "tts_narration",
-    "내레이션 TTS를 합성해 이 PC에 오디오 파일로 저장합니다. 자동 순서: Typecast → ElevenLabs → Supertone → Edge TTS → Supertonic2. 키/런타임이 없을 때 다음 공급자를 고려하며, 합성 실패 후 다른 유료 공급자로 재시도하지 않습니다. 먼저 recommend_voice로 제작 톤에 맞는 보이스를 선택하세요.",
+    "내레이션 TTS를 합성해 이 PC에 저장합니다. 자동 순서: Typecast → ElevenLabs → Supertone → Edge → Supertonic2. 확정된 일시 거절에만 폴백하며, 명시 보이스는 fallbackVoices가 있어야 교체합니다. 접수 후 결과 불명·정책·인증 오류는 재합성하지 않습니다. 먼저 recommend_voice로 톤에 맞는 보이스를 고르세요.",
     {
       ...productionFields,
       text: z.string().optional().describe("생략 시 productionPath의 기획 대본"),
+      ...ttsFallbackFields,
       provider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("기본 자동: Typecast→ElevenLabs→Supertone→Edge→Supertonic2. 명시 선택/저장된 보이스는 유지"),
       voice: z.string().optional().describe("보이스 이름(라벨)"),
       speed: z.number().optional().describe("기본 1"),
       stability: z.number().min(0).max(1).optional(), style: z.number().min(0).max(1).optional(),
       modelId: z.string().optional(), similarityBoost: z.number().min(0).max(1).optional(), speakerBoost: z.boolean().optional(),
     },
-    wrapCloudHandler(config, async ({ text, provider, voice = "", speed, productionPath, productionProfile, stability, style, modelId, similarityBoost, speakerBoost }) => {
+    wrapCloudHandler(config, async ({ text, provider, voice = "", speed, productionPath, productionProfile, stability, style, modelId, similarityBoost, speakerBoost, fallbackVoices, allowProviderFallback }) => {
       const context = readProductionContext(config.stateDir, productionPath);
       productionProfile = context?.productionProfile || productionProfile;
       text ??= context?.narrationScript;
@@ -731,13 +747,21 @@ export function registerCloudTools(server, config, api) {
       voice ||= context?.voice?.voiceId || "";
       if (!text?.trim()) return textResult("대본(text/productionPath)이 필요합니다.", { isError: true });
       if (productionProfile?.deliveryStyle === "casual-social" && !voice) return textResult("먼저 recommend_voice에 productionPath를 전달해 커뮤니티형 보이스를 선정하세요.", { isError: true });
-      const body = buildTtsRequestBody(provider, { productionProfile, costEventId: createUsageEventId(`mcp-tts-${provider}`), modelId, similarityBoost, speakerBoost, speed, stability, style, text, voice });
+      const body = buildTtsRequestBody(provider, { productionProfile, costEventId: createUsageEventId(`mcp-tts-${provider}`), modelId, similarityBoost, speakerBoost, speed, stability, style, text, voice, fallbackVoices, allowProviderFallback });
       const result = await requestTtsBinary(api, config, selection, body);
+      provider = result.provider || provider;
+      voice = result.voiceId || voice;
       const saved = saveMediaBuffer(config.stateDir, provider === "supertonic2" ? "narration.wav" : "narration.mp3", result.buffer, { contentType: result.contentType });
       const durationSec = audioDurationSecFromFile(saved.filePath);
       return jsonResult({
-        productionPath: saveProductionContext(config.stateDir, { ...context, productionProfile, narrationScript: text, tts: { provider, filePath: saved.filePath, durationSec, voiceId: voice } }),
+        productionPath: saveProductionContext(config.stateDir, { ...context, productionProfile, narrationScript: text,
+          ...(result.providerFallback ? { voice: { provider, voiceId: voice, reason: "사용자가 허용한 공급자별 대체 보이스" } } : {}),
+          tts: { provider, filePath: saved.filePath, durationSec, voiceId: voice } }),
         provider,
+        primaryProvider: result.primaryProvider || provider,
+        providerFallback: result.providerFallback === true,
+        accountCostEvents: result.accountCostEvents || [],
+        hasAccountCostEvents: true,
         executionTarget: selection.executionTarget,
         durationWarning: durationReview(productionProfile?.targetDurationSec, durationSec),
         bytes: saved.bytes,
@@ -1464,17 +1488,18 @@ export function registerCloudTools(server, config, api) {
   // ── 시간 동기 자막 TTS — 쇼츠 하단자막용 ─────────────────────────────────────
   server.tool(
     "tts_narration_with_captions",
-    "TTS 오디오와 자막을 만듭니다. 자동 순서: Typecast→ElevenLabs→Supertone→Edge→Supertonic2, 명시 보이스/공급자는 유지. ElevenLabs는 실제 char-level 타이밍, 나머지는 실측 오디오 길이에 비례한 추정 자막(timingSource 확인)입니다. 먼저 recommend_voice로 제작 톤에 맞는 보이스를 고르세요. 자동 추가 STT 과금이나 다른 공급자로의 재합성은 하지 않습니다.",
+    "TTS 오디오와 자막을 만듭니다. 순서 Typecast→ElevenLabs→Supertone→Edge→Supertonic2. 명시 목소리는 fallbackVoices 없이 변경하지 않습니다. ElevenLabs 선택 시 실제 char-level 타이밍을 유지하며 해당 정밀 기능은 대체하지 않습니다. 나머지는 실측 오디오 길이 기반 추정 자막이며 추가 STT 과금은 없습니다.",
     {
       ...productionFields,
       text: z.string().optional().describe("생략 시 제작 핸들의 기획 대본 그대로 합성. 사실·인용을 바꾸거나 뉴스체로 재작성하지 마세요."),
+      ...ttsFallbackFields,
       provider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("기본 자동 선택 또는 제작 핸들에 선정된 공급자"),
       voice: z.string().optional().describe("보이스 이름 또는 ID (생략 시 기본 보이스)"),
       speed: z.number().optional().describe("기본 1 (0.7~1.2)"),
       modelId: z.string().optional(), stability: z.number().min(0).max(1).optional(),
       style: z.number().min(0).max(1).optional(), similarityBoost: z.number().min(0).max(1).optional(), speakerBoost: z.boolean().optional(),
     },
-    wrapCloudHandler(config, async ({ text, provider, voice = "", speed, productionPath, productionProfile, modelId, stability, style, similarityBoost, speakerBoost }) => {
+    wrapCloudHandler(config, async ({ text, provider, voice = "", speed, productionPath, productionProfile, modelId, stability, style, similarityBoost, speakerBoost, fallbackVoices, allowProviderFallback }) => {
       const context = readProductionContext(config.stateDir, productionPath);
       productionProfile = context?.productionProfile || productionProfile;
       text ??= context?.narrationScript;
@@ -1489,16 +1514,21 @@ export function registerCloudTools(server, config, api) {
         return textResult("커뮤니티형 음성을 위해 먼저 recommend_voice에 productionPath를 전달하고, 반환된 productionPath 또는 보이스 ID를 사용하세요.", { isError: true });
       }
       if (provider !== "elevenlabs") {
-        const body = buildTtsRequestBody(provider, { productionProfile, text, voice, speed, modelId, costEventId: createUsageEventId(`mcp-tts-${provider}-captions`) });
+        const body = buildTtsRequestBody(provider, { productionProfile, text, voice, speed, modelId, fallbackVoices, allowProviderFallback, costEventId: createUsageEventId(`mcp-tts-${provider}-captions`) });
         const result = await requestTtsBinary(api, config, selection, body);
+        provider = result.provider || provider;
+        voice = result.voiceId || voice;
         const saved = saveMediaBuffer(config.stateDir, provider === "supertonic2" ? "narration-captions.wav" : "narration-captions.mp3", result.buffer, { contentType: result.contentType });
         const durationSec = audioDurationSecFromFile(saved.filePath);
         const subtitleLines = estimateTtsSubtitleLines(text, durationSec);
         const timingSource = "estimated-from-audio-duration";
         const updatedProductionPath = saveProductionContext(config.stateDir, { ...context, productionProfile, narrationScript: text,
+          ...(result.providerFallback ? { voice: { provider, voiceId: voice, reason: "사용자가 허용한 공급자별 대체 보이스" } } : {}),
           tts: { provider, durationSec, filePath: saved.filePath, subtitleLines, voiceId: voice, timingSource },
         });
         return jsonResult({ productionPath: updatedProductionPath, productionProfile, provider, executionTarget: selection.executionTarget,
+          primaryProvider: result.primaryProvider || provider, providerFallback: result.providerFallback === true,
+          accountCostEvents: result.accountCostEvents || [], hasAccountCostEvents: true,
           durationSec, durationWarning: durationReview(productionProfile?.targetDurationSec, durationSec), filePath: saved.filePath,
           lineCount: subtitleLines.length, subtitleLines, timingSource,
           warnings: [durationSec > 0 ? "자막은 실측 오디오 길이 기준 추정입니다. 최종 렌더 전 발화와 동기를 확인하세요." : "오디오 길이를 측정하지 못해 자막을 만들지 않았습니다. 저장된 오디오를 확인하세요. 자동 재합성하지 않습니다."],

package/lib/companion-tools.mjs

@@ -9,6 +9,7 @@ import {
 import { detectRemoteEnvironment } from "./config.mjs";
 import { durationReview, reviewProductionPayload } from "./production-context.mjs";
 import { readPayloadHandle, saveMediaBuffer } from "./media-store.mjs";
+import { restoreReviewRenderSources } from "./review-sources.mjs";
 import {
   checkRenderPayloadSize,
   sanitizeRenderPayload,
@@ -176,6 +177,11 @@ export function registerCompanionTools(server, config) {
       }
 
       const { payload: cleaned, warnings } = sanitizeRenderPayload(resolvedPayload);
+      try {
+        restoreReviewRenderSources(cleaned, { stateDir: config.stateDir, fromSavedPayload: Boolean(payloadPath) });
+      } catch (error) {
+        return textResult(`리뷰 원본 검증 실패: ${String(error?.message || error)}`, { isError: true });
+      }
       const productionReview = reviewProductionPayload(cleaned);
       if (!productionReview.pass) {
         return textResult(JSON.stringify({ error: "PRODUCTION_SPEC_MISMATCH", ...productionReview }, null, 2), { isError: true });

package/lib/config.mjs

@@ -2,7 +2,7 @@ import { homedir } from "node:os";
 import path from "node:path";
 
 // 프록시 버전 — 서버가 X-AImakeAll-MCP-Version 으로 하한을 강제(426)할 수 있다.
-export const MCP_PROXY_VERSION = "0.12.0";
+export const MCP_PROXY_VERSION = "0.14.0";
 
 export const DEFAULT_API_BASE = "https://aimakeall.com";
 export const DEFAULT_COMPANION_URL = "http://127.0.0.1:9876";

package/lib/production-context.mjs

@@ -11,7 +11,7 @@ export function readProductionContext(stateDir, productionPath) {
   if (!productionPath) return null;
   const value = readPayloadHandle(productionPath, { stateDir });
   if (value?.kind !== "aimakeall-production" || value.version !== 1 || !value.productionId) {
-    throw new Error("productionPath는 plan_shorts_video 또는 TTS가 반환한 제작 핸들이어야 합니다.");
+    throw new Error("productionPath는 plan_* 또는 TTS가 반환한 제작 핸들이어야 합니다.");
   }
   return value;
 }