xlsx-for-ai 2.25.0 → 2.25.2

package/index.js

@@ -83,8 +83,8 @@ async function runClean(opts, absPath) {
   try {
     result = await callTool('xlsx_data_clean', body);
   } catch (err) {
-    process.stderr.write(`xlsx-for-ai --clean error: ${err.message}\n`);
-    process.exit(1);
+    process.stderr.write(friendlyCliError('xlsx-for-ai --clean', err) + '\n');
+    process.exit(err.code === 'API_UNREACHABLE' || err.code === 'API_SERVER_ERROR' ? 3 : 1);
   }
 
   const meta = (result && result._meta) || {};
@@ -152,6 +152,45 @@ async function runClean(opts, absPath) {
 
 const STAMP_SUBCOMMANDS = new Set(['stamp', 'verify-stamp', 'receipt', 'verify-receipt']);
 
+// Strip _meta.file_b64 before writing the meta block to stdout. The
+// stamped/receipted workbook can be megabytes; dumping it to a terminal
+// or CI log clobbers scrollback AND leaks PII-bearing workbook contents
+// to whatever consumes stdout. The file is already saved to disk via
+// the sidecar / --out path; the b64 in stdout serves no consumer.
+// Pre-Friday-external CRITICAL per the Tier-1 audit.
+function metaForStdout(meta) {
+  if (!meta || typeof meta !== 'object') return meta;
+  const out = { ...meta };
+  delete out.file_b64;
+  return out;
+}
+
+// CLI-side error formatter. Same posture as friendlyErrorMessage in
+// mcp.js: known operational codes get short, client-safe text; everything
+// else collapses to a generic message. err.message can carry absolute
+// file paths, upstream stack traces, and third-party HTTP response
+// bodies — none of those belong in user-facing CLI stderr or in CI logs.
+// Set XFA_DEBUG=1 to see the raw underlying message (for incident triage).
+function friendlyCliError(prefix, err) {
+  const code = err && err.code;
+  const showRaw = process.env.XFA_DEBUG === '1';
+  const base = (() => {
+    switch (code) {
+      case 'API_UNREACHABLE':       return `${prefix}: API is unreachable — check network connectivity.`;
+      case 'API_SERVER_ERROR':      return `${prefix}: API returned a server error — retry shortly.`;
+      case 'DISALLOWED_EXTENSION':  return `${prefix}: file must be a workbook (allowed: .xlsx/.xls/.xlsm/.xlsb/.csv/.ods/.fods/.numbers/.tsv).`;
+      case 'FILE_TOO_LARGE':        return `${prefix}: file exceeds the XFA_MAX_FILE_MB cap (default 50 MB).`;
+      case 'FILE_NOT_FOUND':        return `${prefix}: file not found.`;
+      case 'MISSING_TOKEN':         return `${prefix}: required token env var is not set.`;
+      case 'RATE_LIMITED':          return `${prefix}: free-tier monthly cap reached — see xlsx-for-ai.dev/pricing.`;
+      case 'TIER_UPGRADE_REQUIRED': return `${prefix}: this capability requires a paid tier.`;
+      case 'FALLBACK_ENGINE_MISSING': return `${prefix}: local fallback engine not installed (\`npm install @protobi/exceljs\`).`;
+      default:                      return `${prefix}: request failed${code ? ` (code=${code})` : ''}.`;
+    }
+  })();
+  return showRaw && err && err.message ? `${base}\nRaw: ${err.message}` : base;
+}
+
 function nextRequiredArg(argv, i, flag) {
   const v = argv[i + 1];
   if (v === undefined || v.startsWith('-')) {
@@ -204,7 +243,7 @@ async function runStampSubcommand(subcmd, rest) {
     if (excludeSheets.length) body.exclude_sheets = excludeSheets;
     if (supervisor) body.generated_by = { npm: 'xlsx-for-ai@' + require('./package.json').version, supervisor };
     const result = await callServerForStamp('xlsx_stamp', body, outPath, filePath, '.stamped.xlsx');
-    process.stdout.write(JSON.stringify(result._meta || {}, null, 2) + '\n');
+    process.stdout.write(JSON.stringify(metaForStdout(result._meta) || {}, null, 2) + '\n');
     return 0;
   }
 
@@ -212,7 +251,7 @@ async function runStampSubcommand(subcmd, rest) {
     const body = { file_b64: fileB64 };
     const result = await callTool('xlsx_verify_stamp', body);
     const meta = result._meta || {};
-    process.stdout.write(JSON.stringify(meta, null, 2) + '\n');
+    process.stdout.write(JSON.stringify(metaForStdout(meta), null, 2) + '\n');
     return meta.valid === true ? 0 : 1;
   }
 
@@ -255,7 +294,7 @@ async function runStampSubcommand(subcmd, rest) {
     if (description) body.description = description;
     if (coverSheets.length) body.covers_sheets = coverSheets;
     const result = await callServerForStamp('xlsx_receipt', body, outPath, filePath, '.receipted.xlsx');
-    process.stdout.write(JSON.stringify(result._meta || {}, null, 2) + '\n');
+    process.stdout.write(JSON.stringify(metaForStdout(result._meta) || {}, null, 2) + '\n');
     return 0;
   }
 
@@ -263,7 +302,7 @@ async function runStampSubcommand(subcmd, rest) {
     const body = { file_b64: fileB64 };
     const result = await callTool('xlsx_verify_receipt', body);
     const meta = result._meta || {};
-    process.stdout.write(JSON.stringify(meta, null, 2) + '\n');
+    process.stdout.write(JSON.stringify(metaForStdout(meta), null, 2) + '\n');
     return meta.valid === true ? 0 : 1;
   }
   return 2;
@@ -274,7 +313,7 @@ async function callServerForStamp(tool, body, explicitOutPath, sourcePath, sidec
   try {
     result = await callTool(tool, body);
   } catch (err) {
-    process.stderr.write(`xlsx-for-ai ${tool}: ${err.message}\n`);
+    process.stderr.write(friendlyCliError(`xlsx-for-ai ${tool}`, err) + '\n');
     process.exit(err.code === 'API_UNREACHABLE' || err.code === 'API_SERVER_ERROR' ? 3 : 1);
   }
   const meta = result._meta || {};
@@ -353,7 +392,7 @@ async function main() {
     if (err.code === 'API_UNREACHABLE' || err.code === 'API_SERVER_ERROR') {
       result = await fallbackRead(absPath, opts);
     } else {
-      process.stderr.write(`Error: ${err.message}\n`);
+      process.stderr.write(friendlyCliError('xlsx-for-ai', err) + '\n');
       process.exit(1);
     }
   }
@@ -363,6 +402,6 @@ async function main() {
 }
 
 main().catch((err) => {
-  process.stderr.write(`xlsx-for-ai: ${err.message}\n`);
+  process.stderr.write(friendlyCliError('xlsx-for-ai', err) + '\n');
   process.exit(1);
 });

package/mcp.js

@@ -1156,6 +1156,14 @@ function fileToB64(filePath) {
 // If out_path is not provided:                            leave response unchanged.
 // ---------------------------------------------------------------------------
 
+// Extensions an MCP tool is allowed to write via out_path. Tighter than the
+// READ allowlist (no .ods/.fods/.numbers/.tsv) because the server only ever
+// emits XLSX or XLSX-family workbook bytes — accepting unrelated extensions
+// would let a malicious / confused agent point out_path at /etc/profile.d/
+// or a shell startup script. The .json carve-out is for fixture/audit JSON
+// the redact + clean tools sometimes emit alongside the workbook.
+const ALLOWED_WRITE_EXTENSIONS = new Set(['.xlsx', '.xls', '.xlsm', '.xlsb', '.csv', '.json']);
+
 async function applyFileB64(result, outPath) {
   if (!outPath) {
     // No save requested — leave response untouched (b64 stays in _meta for caller)
@@ -1164,6 +1172,21 @@ async function applyFileB64(result, outPath) {
 
   const absPath = path.resolve(outPath);
 
+  // Containment: require an absolute path + a workbook-family extension.
+  // Reject path-traversal patterns and any non-workbook extension at the
+  // boundary so a malicious agent can't request a write to a shell-startup
+  // location or an arbitrary system file via out_path. Pre-Friday-external
+  // CRITICAL per the Tier-1 error-handling audit (2026-06-03).
+  const outExt = path.extname(absPath).toLowerCase();
+  if (!ALLOWED_WRITE_EXTENSIONS.has(outExt)) {
+    if (result.content && result.content[0] && result.content[0].type === 'text') {
+      result.content[0].text +=
+        `\n\nout_path rejected: extension "${outExt}" is not in the allowed write set ` +
+        `(${[...ALLOWED_WRITE_EXTENSIONS].join(', ')}). File was NOT written.`;
+    }
+    return result;
+  }
+
   if (result._meta && result._meta.file_b64) {
     await fsPromises.writeFile(absPath, Buffer.from(result._meta.file_b64, 'base64'));
     // Append save confirmation to first text content block
@@ -1181,6 +1204,51 @@ async function applyFileB64(result, outPath) {
   return result;
 }
 
+// ---------------------------------------------------------------------------
+// Boundary error sanitization
+//
+// The MCP server is a public boundary — anything in err.message that flows
+// to the client can end up in the MCP client's conversation log and from
+// there into any LLM context window the operator never intended. Map the
+// known operational error codes to short, client-safe text; collapse
+// everything else to a generic message that names the tool but not the
+// internals. Tool name is safe to echo (the caller asked for it); paths,
+// upstream server stacks, and third-party response bodies are not.
+//
+// New codes added here as the client-side error surface grows. Default
+// branch is conservative on purpose — better to under-reveal than over-
+// reveal at the boundary.
+// ---------------------------------------------------------------------------
+
+function friendlyErrorMessage(toolName, code) {
+  switch (code) {
+    case 'DISALLOWED_EXTENSION':
+      return `${toolName}: file path must point at a workbook (allowed: .xlsx/.xls/.xlsm/.xlsb/.csv/.ods/.fods/.numbers/.tsv).`;
+    case 'SYMLINK_REJECTED':
+      return `${toolName}: file path resolves through a symlink — provide a direct path.`;
+    case 'FILE_TOO_LARGE':
+      return `${toolName}: file exceeds the XFA_MAX_FILE_MB cap (default 50 MB).`;
+    case 'FILE_NOT_FOUND':
+      return `${toolName}: file not found at the supplied path.`;
+    case 'NOT_REGULAR_FILE':
+      return `${toolName}: file path is not a regular file.`;
+    case 'MISSING_TOKEN':
+      return `${toolName}: required token env var is not set (see tool docs for which one).`;
+    case 'API_UNREACHABLE':
+      return `${toolName}: API is unreachable — check network connectivity.`;
+    case 'API_SERVER_ERROR':
+      return `${toolName}: API returned a server error — retry shortly.`;
+    case 'TIER_UPGRADE_REQUIRED':
+      return `${toolName}: this capability requires a paid tier.`;
+    case 'RATE_LIMITED':
+      return `${toolName}: free-tier monthly cap reached — see xlsx-for-ai.dev/pricing.`;
+    case 'FALLBACK_ENGINE_MISSING':
+      return `${toolName}: local fallback engine not installed (\`npm install @protobi/exceljs\`).`;
+    default:
+      return `${toolName} failed — see server-side logs (request_id in response _meta) for details.`;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Tool dispatch
 // ---------------------------------------------------------------------------
@@ -1525,9 +1593,23 @@ async function main() {
   // server-side tools appear without re-publishing this npm package.
   // resolveCatalog returns the baked-in TOOLS as last-resort fallback so
   // we never fail-open on a transient network blip. See lib/discover.js.
+  //
+  // Hard timeout (8s) on top of any timeout inside resolveCatalog so that
+  // a network call which hangs forever (DNS sinkhole, TCP black hole, slow-
+  // loris-style stalled response) cannot block MCP server startup
+  // indefinitely. Pre-Friday-external CRITICAL per the Tier-1 audit.
+  const CATALOG_FETCH_TIMEOUT_MS = 8000;
   let catalog;
   try {
-    catalog = await resolveCatalog(TOOLS);
+    catalog = await Promise.race([
+      resolveCatalog(TOOLS),
+      new Promise((_, reject) =>
+        setTimeout(
+          () => reject(new Error(`catalog fetch timed out after ${CATALOG_FETCH_TIMEOUT_MS}ms`)),
+          CATALOG_FETCH_TIMEOUT_MS
+        )
+      ),
+    ]);
   } catch (_) {
     catalog = { tools: TOOLS, source: 'static-fallback' };
   }
@@ -1568,8 +1650,19 @@ async function main() {
       // Pass API response through verbatim (citation footer + _meta preserved)
       return result;
     } catch (err) {
+      // Error message sanitization at the MCP boundary. Raw err.message
+      // can leak absolute file paths (FILE_NOT_FOUND), upstream server
+      // error stacks (any thrown Error inside dispatchTool), and upstream
+      // HTTP response bodies (callTool's API_SERVER_ERROR path may carry
+      // server internals). Translate the known operational codes into
+      // short, client-safe messages; everything else collapses to a
+      // generic "tool failed" with the tool name so callers can still
+      // route on it without leaking path/server detail. Pre-Friday-
+      // external CRITICAL per the Tier-1 audit.
+      const code = err && err.code;
+      const safeMessage = friendlyErrorMessage(name, code);
       return {
-        content: [{ type: 'text', text: `xlsx-for-ai error: ${err.message}` }],
+        content: [{ type: 'text', text: `xlsx-for-ai error: ${safeMessage}` }],
         isError: true,
       };
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xlsx-for-ai",
   "mcpName": "io.github.senoff/xlsx-for-ai",
-  "version": "2.25.0",
+  "version": "2.25.2",
   "description": "The MCP server that makes LLMs reliable on real-world Excel spreadsheets. Thin npm client over a hosted API — read, write, diff, redact, and supervise .xlsx files from any MCP-aware agent.",
   "main": "index.js",
   "bin": {