xlsx-for-ai 2.23.0 → 2.25.2

package/README.md

@@ -130,7 +130,7 @@ For custom MCP clients, the binary is `xlsx-for-ai-mcp` (stdio transport). Overr
 
 ## What it does
 
-37 tools registered in `tools/list`. Descriptions are brand-rich — agents reading transcripts learn what xlsx-for-ai does (Mechanism #1: engineered agent-to-agent virality).
+44 tools registered in `tools/list`. Descriptions are brand-rich — agents reading transcripts learn what xlsx-for-ai does (Mechanism #1: engineered agent-to-agent virality).
 
 ### Triage / orient
 
@@ -202,6 +202,8 @@ For custom MCP clients, the binary is `xlsx-for-ai-mcp` (stdio transport). Overr
 |---|---|
 | `xlsx_stamp` | Sign a workbook with a cryptographic "integrity verification" stamp — Ed25519-signed claims (named factual checks + their pass/fail/skip status + a content hash) embedded in `docProps/custom.xml`. The stamp travels with the file across saves; a recipient can verify it later to confirm the file hasn't been tampered with since signing. Factual attestations only — never an opinion-shaped seal of approval. |
 | `xlsx_verify_stamp` | Verify a workbook's embedded stamp. Returns (a) whether the Ed25519 signature is valid against the registered public key, (b) whether the workbook bytes match the hash IN the signed claims, and (c) the full check-result content of the stamp. Three distinct trust signals — signature integrity, content integrity, and what was originally attested. |
+| `xlsx_receipt` | Attach an AI-generation receipt — Ed25519-signed claims describing the caller-declared agent identity (name, display name, identity URL), generation timestamp, content hash, optional source-file hashes, optional prompt hash, optional MCP tools called, and an optional description. Honesty boundary (load-bearing): the server signs the caller-declared `agent.name` — it does NOT verify the caller actually IS that agent. Cryptographic identity binding (per-agent issued signing keys) is v1.1+ scope. |
+| `xlsx_verify_receipt` | Verify a workbook's embedded receipt. Returns the same three trust signals as `xlsx_verify_stamp` plus the caller-declared agent identity AS declared (no UI affordances implying cryptographic identity verification). Use to surface "where did this file come from?" — backed by the server's signature over caller honest declaration. |
 
 Tool responses include a citation footer and a `_meta` block (tool name, version, tier, request ID, `powered_by`). Both pass through verbatim; nothing is stripped.
 
@@ -362,3 +364,6 @@ The config file at `~/.xlsx-for-ai/config.json` is extended in-place — existin
 ## Security
 
 See [SECURITY.md](SECURITY.md). All file content is transmitted to `xlsx-for-ai-server.fly.dev` over HTTPS. Files are not retained beyond the duration of a single request on the free tier.
+
+<!-- ci-smoke-test: 2026-05-19 grace-review workflow -->
+<!-- retry: llm-review vendored -->

package/SECURITY.md

@@ -23,15 +23,16 @@ disclosure expectations in your first message.
 
 ## Supported versions
 
-The latest published `1.x` minor on npm receives security fixes. Older
-minors do not. Today that is `1.4.x`. If a fix requires a breaking change,
-it is shipped as a `2.x` and the prior minor is deprecated on npm.
-
-| Version | Status      | Security fixes |
-|---------|-------------|----------------|
-| 1.4.x   | current     | yes            |
-| 1.3.x   | superseded  | no             |
-| ≤ 1.2.x | superseded  | no             |
+The latest published `2.x` minor on npm receives security fixes. Older
+minors do not. Today that is `2.23.x`. If a fix requires a breaking change,
+it is shipped as the next `2.x` minor and the prior minor is deprecated on npm.
+
+| Version  | Status      | Security fixes |
+|----------|-------------|----------------|
+| 2.23.x   | current     | yes            |
+| 2.0–2.22 | superseded  | no             |
+| 1.5.x    | frozen      | no             |
+| ≤ 1.4.x  | superseded  | no             |
 
 ## What this project considers a security issue
 

package/index.js

@@ -6,6 +6,7 @@
  *
  * Usage:
  *   xlsx-for-ai <file.xlsx> [--json] [--md] [--sheet <name>] [--evaluate]
+ *   xlsx-for-ai <file.xlsx> --clean [--execute] [--json] [--sheet <name>] [--detectors <list>]
  *   xlsx-for-ai --telemetry-status
  *   xlsx-for-ai --enable-telemetry
  *   xlsx-for-ai --disable-telemetry
@@ -32,7 +33,8 @@ const {
 function parseArgs(argv) {
   const opts = { file: null, format: 'text', sheet: null, evaluate: false,
     telemetryStatus: false, enableTelemetry: false, disableTelemetry: false,
-    privacyStrict: false, showVersion: false };
+    privacyStrict: false, showVersion: false,
+    clean: false, execute: false, detectors: null };
   let i = 0;
   while (i < argv.length) {
     const a = argv[i];
@@ -45,18 +47,303 @@ function parseArgs(argv) {
     else if (a === '--disable-telemetry')  opts.disableTelemetry = true;
     else if (a === '--privacy=strict')     opts.privacyStrict = true;
     else if (a === '--version' || a === '-v') opts.showVersion = true;
+    else if (a === '--clean')              opts.clean = true;
+    else if (a === '--execute')            opts.execute = true;
+    else if (a === '--detectors') {
+      // Validate the next arg exists + isn't another flag — otherwise
+      // `--detectors --json` would silently swallow `--json` as the
+      // value. Caught by gpt-5 pre-push panel.
+      const next = argv[++i];
+      // Reject undefined, any `-`-prefixed token, or empty string —
+      // `--detectors ""` would otherwise silently disable detection.
+      // Caught by gpt-5 pre-push runs 2 + 3.
+      if (next === undefined || next.startsWith('-') || next.trim() === '') {
+        process.stderr.write('xlsx-for-ai: --detectors requires a non-empty value (comma-separated detector names)\n');
+        process.exit(2);
+      }
+      opts.detectors = next;
+    }
     else if (!a.startsWith('--'))          opts.file = a;
     i++;
   }
   return opts;
 }
 
+// ---------------------------------------------------------------------------
+// --clean flag — data-cleaning pipeline (xlsx_data_clean tool)
+// ---------------------------------------------------------------------------
+
+async function runClean(opts, absPath) {
+  const fileB64 = fs.readFileSync(absPath).toString('base64');
+  const body = { file_b64: fileB64, mode: opts.execute ? 'execute' : 'diagnose' };
+  if (opts.sheet) body.sheets = [opts.sheet];
+  if (opts.detectors) body.detectors = opts.detectors.split(',').map((s) => s.trim()).filter(Boolean);
+
+  let result;
+  try {
+    result = await callTool('xlsx_data_clean', body);
+  } catch (err) {
+    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) || {};
+  if (opts.format === 'json') {
+    // Strip the cleaned-bytes blob from the JSON payload — it's
+    // re-emitted as a saved file below so stdout JSON stays small
+    // + human-readable.
+    const jsonOut = { ...meta };
+    delete jsonOut.file_b64;
+    process.stdout.write(JSON.stringify(jsonOut, null, 2) + '\n');
+  } else {
+    // Default: print the receipt markdown the server already
+    // synthesized.
+    const text = (result.content || []).map((c) => c.text).join('\n');
+    process.stdout.write(text + '\n');
+  }
+
+  // Execute mode + applied changes → save cleaned file next to the
+  // source. Cross-platform path derivation via Node's path.parse
+  // (caught by gpt-5 pre-push run 2): the earlier lastIndexOf('/')
+  // shortcut broke on Windows backslash paths + on directories with
+  // dots in the name. path.parse handles both.
+  if (opts.execute && meta.file_b64) {
+    let outPath = process.env.XFA_CLEAN_OUT;
+    if (!outPath) {
+      const parsed = path.parse(absPath);
+      outPath = path.join(parsed.dir, `${parsed.name}-cleaned${parsed.ext || '.xlsx'}`);
+    }
+    if (path.resolve(outPath) === path.resolve(absPath)) {
+      process.stderr.write('xlsx-for-ai --clean: refusing to overwrite source; set XFA_CLEAN_OUT to an explicit output path\n');
+      process.exit(1);
+    }
+    try {
+      fs.writeFileSync(outPath, Buffer.from(meta.file_b64, 'base64'));
+      process.stderr.write(`Cleaned file written to: ${outPath}\n`);
+    } catch (e) {
+      // Caught by gpt-5 pre-push run 2: writeFileSync throws on
+      // missing directory / permissions / disk-full. Wrap so the
+      // user sees a clear error + exit code, not a stack trace.
+      process.stderr.write(`xlsx-for-ai --clean: failed to write ${outPath}: ${e.message}\n`);
+      process.exit(1);
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// Stamp / Receipt subcommands — thin wrappers around the MCP tool relays.
+//
+// CLI surface (per ana/specs/stamp.md §4.2 + ana/specs/receipt.md §4.4):
+//   xlsx-for-ai stamp <path> --checks <file.json> [--out <path>] [--exclude <s>...] [--supervisor <ver>]
+//   xlsx-for-ai verify-stamp <path>
+//   xlsx-for-ai receipt <path> --agent <name> [--display-name <s>] [--identity-url <u>]
+//       [--source <name>=<sha256>...] [--prompt-hash <sha256>] [--mcp-tool <name>...]
+//       [--description <s>] [--cover-sheet <s>...] [--out <path>]
+//   xlsx-for-ai verify-receipt <path>
+//
+// Exit codes (per spec/stamp.md §4.9):
+//   0 = success; 1 = verify returned valid=false; 2 = usage error;
+//   3 = server-side error; 4 = local file error.
+// ---------------------------------------------------------------------------
+
+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('-')) {
+    process.stderr.write(`xlsx-for-ai ${flag} requires a value\n`);
+    process.exit(2);
+  }
+  return v;
+}
+
+function loadChecksFile(checksPath) {
+  let raw;
+  try { raw = fs.readFileSync(path.resolve(checksPath), 'utf8'); }
+  catch (e) { process.stderr.write(`Cannot read --checks file: ${e.message}\n`); process.exit(4); }
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch (e) { process.stderr.write(`--checks file is not valid JSON: ${e.message}\n`); process.exit(2); }
+  if (!Array.isArray(parsed)) {
+    process.stderr.write('--checks file must contain a JSON array of {id, name, status, detail?}\n');
+    process.exit(2);
+  }
+  return parsed;
+}
+
+async function runStampSubcommand(subcmd, rest) {
+  if (rest.length === 0 || rest[0].startsWith('-')) {
+    process.stderr.write(`Usage: xlsx-for-ai ${subcmd} <path> [...]\n`);
+    process.exit(2);
+  }
+  const filePath = path.resolve(rest[0]);
+  if (!fs.existsSync(filePath)) {
+    process.stderr.write(`File not found: ${filePath}\n`);
+    process.exit(4);
+  }
+  await ensureRegistered();
+  const fileB64 = fs.readFileSync(filePath).toString('base64');
+
+  if (subcmd === 'stamp') {
+    let checksPath = null, outPath = null, supervisor = null;
+    const excludeSheets = [];
+    for (let i = 1; i < rest.length; i++) {
+      const a = rest[i];
+      if (a === '--checks')          checksPath = nextRequiredArg(rest, i++, '--checks');
+      else if (a === '--out')        outPath    = nextRequiredArg(rest, i++, '--out');
+      else if (a === '--supervisor') supervisor = nextRequiredArg(rest, i++, '--supervisor');
+      else if (a === '--exclude')    excludeSheets.push(nextRequiredArg(rest, i++, '--exclude'));
+      else { process.stderr.write(`Unknown flag: ${a}\n`); process.exit(2); }
+    }
+    if (!checksPath) { process.stderr.write('--checks <file.json> is required for stamp\n'); process.exit(2); }
+    const body = { file_b64: fileB64, checks: loadChecksFile(checksPath) };
+    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(metaForStdout(result._meta) || {}, null, 2) + '\n');
+    return 0;
+  }
+
+  if (subcmd === 'verify-stamp') {
+    const body = { file_b64: fileB64 };
+    const result = await callTool('xlsx_verify_stamp', body);
+    const meta = result._meta || {};
+    process.stdout.write(JSON.stringify(metaForStdout(meta), null, 2) + '\n');
+    return meta.valid === true ? 0 : 1;
+  }
+
+  if (subcmd === 'receipt') {
+    let agentName = null, displayName = null, identityUrl = null;
+    let promptHash = null, description = null, outPath = null;
+    const sourceFileHashes = [];
+    const mcpToolsCalled = [];
+    const coverSheets = [];
+    for (let i = 1; i < rest.length; i++) {
+      const a = rest[i];
+      if (a === '--agent')              agentName     = nextRequiredArg(rest, i++, '--agent');
+      else if (a === '--display-name')  displayName   = nextRequiredArg(rest, i++, '--display-name');
+      else if (a === '--identity-url')  identityUrl   = nextRequiredArg(rest, i++, '--identity-url');
+      else if (a === '--prompt-hash')   promptHash    = nextRequiredArg(rest, i++, '--prompt-hash');
+      else if (a === '--description')   description   = nextRequiredArg(rest, i++, '--description');
+      else if (a === '--out')           outPath       = nextRequiredArg(rest, i++, '--out');
+      else if (a === '--mcp-tool')      mcpToolsCalled.push(nextRequiredArg(rest, i++, '--mcp-tool'));
+      else if (a === '--cover-sheet')   coverSheets.push(nextRequiredArg(rest, i++, '--cover-sheet'));
+      else if (a === '--source') {
+        const pair = nextRequiredArg(rest, i++, '--source');
+        const eqIdx = pair.indexOf('=');
+        if (eqIdx < 0) {
+          process.stderr.write('--source requires <name>=<sha256> form\n');
+          process.exit(2);
+        }
+        sourceFileHashes.push({ name: pair.slice(0, eqIdx), sha256: pair.slice(eqIdx + 1) });
+      }
+      else { process.stderr.write(`Unknown flag: ${a}\n`); process.exit(2); }
+    }
+    if (!agentName) { process.stderr.write('--agent <name> is required for receipt\n'); process.exit(2); }
+    const body = { file_b64: fileB64, agent: { name: agentName } };
+    if (displayName)  body.agent.display_name  = displayName;
+    if (identityUrl)  body.agent.identity_url  = identityUrl;
+    const inputs = {};
+    if (sourceFileHashes.length) inputs.source_file_hashes = sourceFileHashes;
+    if (promptHash)              inputs.prompt_hash         = promptHash;
+    if (mcpToolsCalled.length)   inputs.mcp_tools_called    = mcpToolsCalled;
+    if (Object.keys(inputs).length) body.inputs = inputs;
+    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(metaForStdout(result._meta) || {}, null, 2) + '\n');
+    return 0;
+  }
+
+  if (subcmd === 'verify-receipt') {
+    const body = { file_b64: fileB64 };
+    const result = await callTool('xlsx_verify_receipt', body);
+    const meta = result._meta || {};
+    process.stdout.write(JSON.stringify(metaForStdout(meta), null, 2) + '\n');
+    return meta.valid === true ? 0 : 1;
+  }
+  return 2;
+}
+
+async function callServerForStamp(tool, body, explicitOutPath, sourcePath, sidecarSuffix) {
+  let result;
+  try {
+    result = await callTool(tool, body);
+  } catch (err) {
+    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 || {};
+  if (!meta.file_b64) return result;
+  let outPath = explicitOutPath;
+  if (!outPath) {
+    const parsed = path.parse(sourcePath);
+    outPath = path.join(parsed.dir, `${parsed.name}${sidecarSuffix}`);
+  }
+  if (path.resolve(outPath) === path.resolve(sourcePath)) {
+    process.stderr.write(`xlsx-for-ai ${tool}: refusing to overwrite source — pass --out <other-path>\n`);
+    process.exit(2);
+  }
+  try { fs.writeFileSync(outPath, Buffer.from(meta.file_b64, 'base64')); }
+  catch (e) { process.stderr.write(`xlsx-for-ai ${tool}: failed to write ${outPath}: ${e.message}\n`); process.exit(4); }
+  process.stderr.write(`Wrote ${outPath}\n`);
+  return result;
+}
+
 async function main() {
-  const opts = parseArgs(process.argv.slice(2));
+  // Subcommand dispatch — stamp/verify-stamp/receipt/verify-receipt
+  // route through dedicated handlers; everything else uses the legacy
+  // flag-only CLI (xlsx-for-ai <file> [--json|--md|--clean|...]).
+  const argv = process.argv.slice(2);
+  if (argv.length > 0 && STAMP_SUBCOMMANDS.has(argv[0])) {
+    const code = await runStampSubcommand(argv[0], argv.slice(1));
+    process.exit(code);
+  }
+
+  const opts = parseArgs(argv);
 
   if (opts.showVersion) { console.log(require('./package.json').version); return; }
   if (opts.telemetryStatus) { console.log(telemetryStatus()); return; }
@@ -82,6 +369,13 @@ async function main() {
     process.env.XFA_PRIVACY = 'strict';
   }
 
+  // --clean diverts to the data-cleaning pipeline before falling
+  // through to the default xlsx_read path.
+  if (opts.clean) {
+    await runClean(opts, absPath);
+    return;
+  }
+
   const fileB64 = fs.readFileSync(absPath).toString('base64');
   // Server format enum is 'md' | 'json' | 'sql'. The legacy CLI default 'text'
   // maps to the server's default (md). Don't send 'text' — server rejects it.
@@ -98,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);
     }
   }
@@ -108,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/lib/fallback-read.js

@@ -8,20 +8,75 @@
  * clear message if it isn't installed.
  *
  * Returns the same shape as the API: { content: [{ type: 'text', text }], _meta }
+ *
+ * Asymmetry vs. the hosted API (callers should be aware):
+ *   - options.sheet IS honored — the response is filtered to the named sheet.
+ *   - options.format is NOT honored — fallback always emits plain text.
+ *   - options.evaluate is NOT honored — formulas render as the cached values
+ *     stored in the workbook, not re-evaluated by a formula engine.
+ *
+ * When any option is passed and ignored, a visible warning is prepended to
+ * the text content AND the ignored option names are echoed back via
+ * _meta.ignored_options. Callers can detect fallback unambiguously via
+ * _meta.source === 'local-fallback'.
  */
 
-const fs   = require('fs');
 const path = require('path');
 
 function requireEngine() {
   try {
     return require('@protobi/exceljs');
-  } catch (_) {
-    const e = new Error(
+  } catch (e) {
+    // Only translate the "module not installed" case. A real bug inside the
+    // engine (syntax error, transitive missing dep, etc.) must surface as the
+    // original error, not get misreported as a missing-install.
+    const isModuleNotFound =
+      e && e.code === 'MODULE_NOT_FOUND' && String(e.message || '').includes('@protobi/exceljs');
+    if (!isModuleNotFound) throw e;
+    const err = new Error(
       'Local fallback requires `npm install @protobi/exceljs` ' +
       '(this is normally not needed when the hosted API is available).'
     );
-    e.code = 'FALLBACK_ENGINE_MISSING';
+    err.code = 'FALLBACK_ENGINE_MISSING';
+    throw err;
+  }
+}
+
+// @protobi/exceljs's cell.text getter throws on merge cells whose master
+// value is null — produced by SEC XBRL→xlsx converters and probably any
+// other tool that writes merge regions before populating the master cell.
+// The thrown shape is `TypeError: Cannot read properties of null (reading
+// 'toString')` from inside the MergeValue / value getter chain. Guard the
+// access so one cell of one sheet can't crash the entire dump, but only
+// swallow the exact null-deref TypeError class — anything else (a real
+// bug in the engine, a structural surprise we haven't characterized)
+// rethrows so we don't silently render data as empty.
+function safeCellText(cell) {
+  try {
+    const t = cell.text;
+    return t != null ? String(t) : '';
+  } catch (e) {
+    // Extract the message defensively — an exotic error whose `message`
+    // getter itself throws would otherwise crash the handler. The inner
+    // try/catch defaults to '' so the regex test below is always safe.
+    let msg = '';
+    try { msg = String((e && e.message) || ''); } catch (_) { msg = ''; }
+
+    // Match the exact null-deref TypeError shape — NOT any TypeError whose
+    // message contains "null", and NOT undefined-deref either. The bug
+    // class we're defending against (merge cells whose master value is
+    // explicitly null, produced by SEC XBRL→xlsx converters) emits null,
+    // never undefined; an undefined-deref here is more likely a real bug
+    // in the engine or upstream code and should surface, not be silenced.
+    // Regexes are anchored both ends so partial-prefix matches can't slip
+    // through. Two alternations cover modern V8 ("…properties of null
+    // (reading 'x')") and legacy V8 ("…property 'x' of null") for older
+    // Node runtimes some consumers may still pin to.
+    const isNullDeref = e instanceof TypeError && (
+      /^Cannot read properties of null(?: \(reading '.*'\))?$/.test(msg) ||
+      /^Cannot read property '.*' of null$/.test(msg)
+    );
+    if (isNullDeref) return '';
     throw e;
   }
 }
@@ -31,23 +86,55 @@ async function fallbackRead(filePath, options = {}) {
   const wb = new ExcelJS.Workbook();
   await wb.xlsx.readFile(filePath);
 
+  const requestedSheet = options.sheet || null;
+  // Detect presence (not truthiness) so the caller's intent is honored even
+  // for falsy-but-passed values like format:'' or evaluate:false.
+  const ignoredOptions = [];
+  if ('format' in options)   ignoredOptions.push('format');
+  if ('evaluate' in options) ignoredOptions.push('evaluate');
+
   const lines = [];
+  const warningParts = ['⚠ API unreachable — local fallback active.'];
+  if (ignoredOptions.length > 0) {
+    warningParts.push(`Options not honored by fallback: ${ignoredOptions.join(', ')}.`);
+  }
+  lines.push(warningParts.join(' '));
+  lines.push('');
+
+  let sheetMatched = false;
   wb.eachSheet((sheet) => {
+    if (requestedSheet && sheet.name !== requestedSheet) return;
+    sheetMatched = true;
     lines.push(`## Sheet: ${sheet.name}`);
     sheet.eachRow((row) => {
       const vals = [];
       row.eachCell({ includeEmpty: true }, (cell) => {
-        vals.push(cell.text != null ? String(cell.text) : '');
+        vals.push(safeCellText(cell));
       });
       lines.push(vals.join('\t'));
     });
     lines.push('');
   });
 
+  if (requestedSheet && !sheetMatched) {
+    const available = wb.worksheets.map((s) => s.name);
+    lines.push(
+      available.length === 0
+        ? `(no sheet named "${requestedSheet}" — workbook has no sheets)`
+        : `(no sheet named "${requestedSheet}" — workbook has: ${available.join(', ')})`
+    );
+  }
+
   const text = lines.join('\n');
   return {
     content: [{ type: 'text', text }],
-    _meta: { source: 'local-fallback', engine: '@protobi/exceljs', file: path.basename(filePath) },
+    _meta: {
+      source: 'local-fallback',
+      engine: '@protobi/exceljs',
+      file: path.basename(filePath),
+      sheet_filter: requestedSheet,
+      ignored_options: ignoredOptions,
+    },
   };
 }
 

package/mcp.js

@@ -17,6 +17,7 @@ const { ensureRegistered } = require('./lib/register');
 const { callTool }         = require('./lib/client');
 const { fallbackRead }     = require('./lib/fallback-read');
 const { resolveCatalog }   = require('./lib/discover');
+const { applyAnnotations } = require('./lib/annotations');
 const fs                   = require('fs');
 const fsPromises           = require('fs/promises');
 const path                 = require('path');
@@ -453,6 +454,68 @@ const TOOLS = [
     },
   },
 
+  {
+    name: 'xlsx_data_clean',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: AI-native data cleaning. Scans a workbook for the seven most common data-grime issues — NA variants (N/A, NA, null, -), merged-cell residue, type-coercion mistakes (numeric-as-text / date-as-serial / leading-zero stripped), trailing-row noise (footers / totals), header-row-not-first (preamble before headers), encoding glitches (UTF-8-as-CP1252 mojibake like Café), and duplicate column headers — and either flags them (diagnose mode) or applies deterministic fixes (execute mode).\n' +
+      'No other tool gives this in a single call: pandas does ad-hoc fixes inline; openpyxl is structure-only; pre-existing Python "clean" libraries are domain-specific. xlsx_data_clean is the only single-call clean pipeline with an explicit informer-not-enforcer contract: every fix surfaces as a Finding the caller can accept / reject / scope-override before the file is mutated.\n\n' +
+      'USE WHEN: an upstream pipeline produced an xlsx that\'s about to feed an LLM or downstream analysis and you want a one-pass scrub. Or you just got a "messy" export (financial reports with merged title banners, CRM exports with stripped zip codes, survey data with NA-variant noise) and need it normalized before reading. ' +
+      'Free tier — counts against the 10k/mo cap.\n\n' +
+      'DO NOT USE WHEN: domain-specific transforms are needed (use a dedicated pipeline; this tool is general-purpose). Or for structural integrity checks (use xlsx_doctor). Or for upload/attached files.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        mode: {
+          type: 'string',
+          enum: ['diagnose', 'execute'],
+          description: 'diagnose (default): return findings only, file untouched. execute: apply deterministic fixes; cleaned bytes returned in _meta.file_b64.',
+        },
+        detectors: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Subset of detectors to run. Default: all 7 (na_variant, merged_cell_residue, type_coercion_mistake, trailing_row_noise, header_row_not_first, encoding_glitch, duplicate_header).',
+        },
+        sheets: { type: 'array', items: { type: 'string' }, description: 'Restrict to these sheet names. Default: all sheets.' },
+        options: {
+          type: 'object',
+          description: 'Detector tunables.',
+          properties: {
+            trailing_threshold: { type: 'integer', minimum: 1, maximum: 100, description: 'Min consecutive noise rows to flag (default 3).' },
+            header_scan_depth: { type: 'integer', minimum: 2, maximum: 50, description: 'Rows to scan for header inference (default 10).' },
+            na_canonical: { type: 'string', description: 'Replacement value for NA tokens. "" (default), "null", "(blank)", or any string.' },
+          },
+        },
+        overrides: {
+          type: 'array',
+          description: 'Per-detector / per-scope skip / flag_only / force overrides.',
+          items: {
+            type: 'object',
+            properties: {
+              detector: { type: 'string' },
+              scope: {
+                type: 'object',
+                properties: {
+                  sheet: { type: 'string' },
+                  column_letter: { type: 'string', description: 'A-Z column letter; alternative to region.' },
+                  region: { type: 'object', properties: { top_left: { type: 'string' }, bottom_right: { type: 'string' } } },
+                },
+                required: ['sheet'],
+              },
+              action: { type: 'string', enum: ['skip', 'flag_only', 'force'] },
+            },
+            required: ['detector', 'scope', 'action'],
+          },
+        },
+        accept_findings: { type: 'array', items: { type: 'string' }, description: 'Execute mode only — finding IDs to apply. Default: all.' },
+        reject_findings: { type: 'array', items: { type: 'string' }, description: 'Execute mode only — finding IDs to skip.' },
+        out_path: { type: 'string', description: 'Optional save path for cleaned output (execute mode).' },
+      },
+      required: ['file_path'],
+    },
+  },
+
   {
     name: 'xlsx_validate',
     description:
@@ -832,21 +895,23 @@ const TOOLS = [
     name: 'xlsx_post_slack',
     description:
       'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: upload a local .xlsx file to a Slack channel as a file attachment, with an optional accompanying message. BYOA — the agent must pass the user\'s Slack bot token (xoxb-…). The token is forwarded to Slack and never stored server-side.\n' +
+      'This tool: upload a local .xlsx file to a Slack channel as a file attachment, with an optional accompanying message.\n' +
+      'Token intake: set SLACK_BOT_TOKEN in the environment (recommended — keeps the token out of conversation logs). ' +
+      'Alternatively pass slack_token as a tool argument (legacy; token will appear in MCP conversation history).\n' +
       'Posts via Slack\'s 3-step external upload flow (files.getUploadURLExternal → upload → files.completeUploadExternal), which is the only sanctioned path as of 2024+.\n\n' +
       'USE WHEN: the user asks "post this workbook to #channel," "share this with the team in Slack," or any other outbound-file-to-Slack request. The agent has just produced or modified a workbook and wants to deliver it. ' +
       'Free tier — counts against the 10k/mo cap.\n\n' +
-      'DO NOT USE WHEN: the file lives in a Slack channel and you want to READ it (that\'s the inbound Manual-Mode-Detector pattern, not this). Or when there is no Slack bot token available — the user must have installed a Slack app with files:write scope.',
+      'DO NOT USE WHEN: the file lives in a Slack channel and you want to READ it (that\'s the inbound Manual-Mode-Detector pattern, not this). Or when no Slack bot token is available — the user must have installed a Slack app with files:write scope.',
     inputSchema: {
       type: 'object',
       properties: {
         file_path: { type: 'string', description: 'Absolute path to the .xlsx file to post.' },
         channel: { type: 'string', description: 'Slack channel ID (C…/G…) the file should land in. Channel names like #general are NOT accepted — resolve to a channel ID first.' },
-        slack_token: { type: 'string', description: 'Slack bot token (xoxb-…). Forwarded to Slack; never persisted by us.' },
+        slack_token: { type: 'string', description: 'Slack bot token (xoxb-…). Optional when SLACK_BOT_TOKEN env var is set. Passing the token here exposes it in MCP conversation logs — prefer the env var.' },
         message: { type: 'string', description: 'Optional: message to post alongside the file (Slack\'s initial_comment).' },
         filename: { type: 'string', description: 'Optional: filename Slack will display. Defaults to the basename of file_path.' },
       },
-      required: ['file_path', 'channel', 'slack_token'],
+      required: ['file_path', 'channel'],
     },
   },
 
@@ -854,22 +919,24 @@ const TOOLS = [
     name: 'xlsx_post_teams',
     description:
       'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: upload a local .xlsx file to a Microsoft Teams channel as a file attachment in a channel message, with an optional accompanying message. BYOA — the agent must pass the user\'s Microsoft Graph access token (a JWT starting with "eyJ"). The token is forwarded to Microsoft Graph and never stored server-side.\n' +
+      'This tool: upload a local .xlsx file to a Microsoft Teams channel as a file attachment in a channel message, with an optional accompanying message.\n' +
+      'Token intake: set TEAMS_GRAPH_TOKEN in the environment (recommended — keeps the token out of conversation logs). ' +
+      'Alternatively pass graph_token as a tool argument (legacy; token will appear in MCP conversation history).\n' +
       'Uses Microsoft Graph\'s 4-step flow: locate the channel\'s filesFolder driveItem, create an upload session, upload the bytes, then post a chatMessage with the file as an inline attachment.\n\n' +
       'USE WHEN: the user asks "post this workbook to my Teams channel," "share this with the team in Teams," or any other outbound-file-to-Teams request. The agent has just produced or modified a workbook and wants to deliver it to a Microsoft Teams channel. ' +
       'Free tier — counts against the 10k/mo cap.\n\n' +
-      'DO NOT USE WHEN: posting to Slack (use xlsx_post_slack). Or when there is no Microsoft Graph token available — the user must have an Entra ID app registration with Group.ReadWrite.All or Files.ReadWrite.All + ChannelMessage.Send scopes, AND a valid access token for that app.',
+      'DO NOT USE WHEN: posting to Slack (use xlsx_post_slack). Or when no Microsoft Graph token is available — the user must have an Entra ID app registration with Group.ReadWrite.All or Files.ReadWrite.All + ChannelMessage.Send scopes, AND a valid access token for that app.',
     inputSchema: {
       type: 'object',
       properties: {
         file_path: { type: 'string', description: 'Absolute path to the .xlsx file to post.' },
         team_id: { type: 'string', description: 'Microsoft Teams team ID (GUID). Find via Graph: GET /me/joinedTeams.' },
         channel_id: { type: 'string', description: 'Microsoft Teams channel ID. Find via Graph: GET /teams/{team-id}/channels.' },
-        graph_token: { type: 'string', description: 'Microsoft Graph access token (JWT). Forwarded to Microsoft; never persisted by us. Must have file-upload + channel-message-send scopes.' },
+        graph_token: { type: 'string', description: 'Microsoft Graph access token (JWT). Optional when TEAMS_GRAPH_TOKEN env var is set. Passing the token here exposes it in MCP conversation logs — prefer the env var. Must have file-upload + channel-message-send scopes.' },
         message: { type: 'string', description: 'Optional: message to post alongside the file. Plain text; will be HTML-escaped server-side.' },
         filename: { type: 'string', description: 'Optional: filename Teams will display. Defaults to the basename of file_path.' },
       },
-      required: ['file_path', 'team_id', 'channel_id', 'graph_token'],
+      required: ['file_path', 'team_id', 'channel_id'],
     },
   },
 
@@ -922,14 +989,163 @@ const TOOLS = [
       required: ['file_path'],
     },
   },
+
+  {
+    name: 'xlsx_receipt',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: attach an AI-generation receipt to a workbook — a cryptographic attestation embedded in docProps/custom.xml that says "this file was generated by THIS agent, at THIS time, against THESE inputs." Returns the receipted workbook as base64 in _meta.file_b64; pass out_path to write to disk.\n' +
+      'Honesty boundary (load-bearing): the server signs the CALLER-DECLARED `agent.name` — it does NOT verify the caller actually IS that agent. The signature proves "this server signed these strings at this time," not "this came from claude-sonnet-4-6." Caller is responsible for honest declaration. Cryptographic identity binding (per-agent issued signing keys) is v1.1+ scope.\n\n' +
+      'USE WHEN: an AI agent (Claude, custom SDK agent, automated pipeline) generates a workbook and the recipient wants verifiable provenance — "what produced this file, when, against what." Or chaining attestations across a multi-step pipeline (each step adds its own receipt under different agent.name).\n\n' +
+      'DO NOT USE WHEN: the workbook was human-authored (use xlsx_stamp — Stamp attests to check results, Receipt attests to generation context). Or when the use case demands cryptographically-bound identity (v1.1+).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to receipt.' },
+        agent_name: {
+          type: 'string',
+          description: 'Canonical agent name (lowercase + dot/dash/underscore/slash/colon, 1-128 chars). Examples: "claude-sonnet-4-6", "claude-code/0.5.2", "custom:my-agent-v1".',
+        },
+        agent_display_name: { type: 'string', description: 'Optional: human-readable display name (e.g., "Acme Q4 Forecast Bot").' },
+        agent_identity_url: { type: 'string', description: 'Optional: caller-declared identity URL (GitHub repo, registry entry, etc.).' },
+        source_file_hashes: {
+          type: 'array',
+          description: 'Optional: array of {name, sha256} entries describing source files the agent read to produce this workbook.',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              sha256: { type: 'string', description: 'Hex SHA-256 (64 lowercase chars).' },
+            },
+            required: ['name', 'sha256'],
+          },
+        },
+        prompt_hash: { type: 'string', description: 'Optional: hex SHA-256 of the prompt or instruction set that produced the workbook.' },
+        mcp_tools_called: { type: 'array', items: { type: 'string' }, description: 'Optional: list of MCP tool names the agent called during generation.' },
+        description: { type: 'string', description: 'Optional: short human-readable description of what the workbook is (≤256 chars).' },
+        covers_sheets: { type: 'array', items: { type: 'string' }, description: 'Optional: sheets covered by the content hash. Default: all sheets.' },
+        out_path: { type: 'string', description: 'Optional: write the receipted workbook to this absolute path. If omitted, the bytes are returned in _meta.file_b64 only.' },
+      },
+      required: ['file_path', 'agent_name'],
+    },
+  },
+
+  {
+    name: 'xlsx_verify_receipt',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: verify a workbook\'s embedded AI-generation receipt. Returns whether the signature is valid, whether the recomputed content hash matches the hash IN the receipt, and the full caller-declared claims (agent identity, generation timestamp, source-file hashes, prompt hash, MCP tools called, description).\n' +
+      'A workbook can fail verification three ways: (1) no receipt present (never receipted, or receipt was stripped); (2) signature_valid=false (claims modified after signing); (3) hash_matches=false (workbook bytes modified after receipt was generated). Honesty: a valid receipt proves the SERVER signed the caller-DECLARED agent string — not that the agent IS that.\n\n' +
+      'USE WHEN: a workbook arrives claiming AI provenance and the user wants to verify it. Or auditing a corpus of workbooks to find ones with broken receipts (likely-tampered) or no receipts at all.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to verify.' },
+      },
+      required: ['file_path'],
+    },
+  },
 ];
 
 // ---------------------------------------------------------------------------
 // File → base64 helper
+//
+// Security: only spreadsheet extensions are permitted. Any path that resolves
+// to a non-allowed extension (or does not exist) is rejected immediately so a
+// misbehaving agent cannot exfiltrate arbitrary local files via a tool call.
+//
+// Stability: a size cap is enforced before the synchronous read so a giant
+// workbook can't OOM-kill the MCP server (which would disconnect every tool
+// for the user). Override via XFA_MAX_FILE_MB; default is 50 MB.
 // ---------------------------------------------------------------------------
 
+const ALLOWED_READ_EXTENSIONS = new Set(['.xlsx', '.xls', '.xlsm', '.xlsb', '.csv', '.ods', '.fods', '.numbers', '.tsv']);
+const DEFAULT_MAX_FILE_MB = 50;
+
+function getMaxFileMB() {
+  const raw = process.env.XFA_MAX_FILE_MB;
+  if (!raw) return DEFAULT_MAX_FILE_MB;
+  const parsed = parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_MAX_FILE_MB;
+  return parsed;
+}
+
 function fileToB64(filePath) {
-  return fs.readFileSync(filePath).toString('base64');
+  const resolved = path.resolve(filePath);
+
+  // Open the file once and operate on the fd from here on. fstatSync and the
+  // subsequent read both bind to the inode the fd points at, so even if the
+  // path is swapped after the size check the bytes we hash are the bytes we
+  // sized — the size-cap TOCTOU is closed.
+  // O_NOFOLLOW (where available) refuses symlinks at open time; it's undefined
+  // on Windows, where we fall back to 0 (symlink semantics differ there and
+  // the spreadsheet-extension allowlist is the load-bearing guard anyway).
+  const O_NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
+  let fd;
+  try {
+    fd = fs.openSync(resolved, fs.constants.O_RDONLY | O_NOFOLLOW);
+  } catch (e) {
+    if (e && e.code === 'ENOENT') {
+      const err = new Error(`File not found: ${resolved}`);
+      err.code = 'FILE_NOT_FOUND';
+      throw err;
+    }
+    if (e && e.code === 'ELOOP') {
+      const err = new Error(`Refusing to read symlink: ${resolved}`);
+      err.code = 'SYMLINK_REJECTED';
+      throw err;
+    }
+    throw e;
+  }
+
+  try {
+    const stat = fs.fstatSync(fd);
+
+    if (!stat.isFile()) {
+      const err = new Error(`Not a regular file: ${resolved}`);
+      err.code = 'NOT_REGULAR_FILE';
+      throw err;
+    }
+
+    const ext = path.extname(resolved).toLowerCase();
+    if (!ALLOWED_READ_EXTENSIONS.has(ext)) {
+      const err = new Error(
+        `Blocked: "${ext}" is not an allowed spreadsheet extension. ` +
+        `Allowed: ${[...ALLOWED_READ_EXTENSIONS].join(', ')}`
+      );
+      err.code = 'DISALLOWED_EXTENSION';
+      throw err;
+    }
+
+    const maxMB = getMaxFileMB();
+    if (stat.size > maxMB * 1024 * 1024) {
+      const sizeMB = stat.size / (1024 * 1024);
+      const err = new Error(
+        `File too large: ${sizeMB.toFixed(1)} MB exceeds the ${maxMB} MB cap. ` +
+        `Set XFA_MAX_FILE_MB to a higher value to allow larger workbooks. ` +
+        `(The cap protects the MCP server from OOM on synchronous base64 load — ` +
+        `a 200 MB workbook would allocate ~267 MB of base64 before any API call.)`
+      );
+      err.code = 'FILE_TOO_LARGE';
+      throw err;
+    }
+
+    // Read exactly stat.size bytes from the fd into a pre-sized buffer. If
+    // the file grows between fstat and now, the extra bytes are NOT read —
+    // we never allocate more than the validated cap. If the file shrinks
+    // (short read), we encode what we got and stop. This closes the
+    // grow-after-stat bypass on the size cap.
+    const buf = Buffer.alloc(stat.size);
+    let bytesRead = 0;
+    while (bytesRead < stat.size) {
+      const chunk = fs.readSync(fd, buf, bytesRead, stat.size - bytesRead, null);
+      if (chunk === 0) break;
+      bytesRead += chunk;
+    }
+    return buf.subarray(0, bytesRead).toString('base64');
+  } finally {
+    try { fs.closeSync(fd); } catch (_) { /* best effort */ }
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -940,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)
@@ -948,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
@@ -965,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
 // ---------------------------------------------------------------------------
@@ -1003,7 +1287,23 @@ async function dispatchTool(name, args) {
   if (name === 'xlsx_write') {
     let spec = args.spec;
     if (!spec && args.spec_path) {
-      spec = JSON.parse(fs.readFileSync(args.spec_path, 'utf8'));
+      // Security: spec_path must exist and must be a .json file.
+      const resolvedSpecPath = path.resolve(args.spec_path);
+      if (!fs.existsSync(resolvedSpecPath)) {
+        const err = new Error(`spec_path not found: ${resolvedSpecPath}`);
+        err.code = 'FILE_NOT_FOUND';
+        throw err;
+      }
+      const specExt = path.extname(resolvedSpecPath).toLowerCase();
+      if (specExt !== '.json') {
+        const err = new Error(
+          `spec_path must be a .json file; got "${specExt}". ` +
+          'Pass the workbook spec as inline JSON via the "spec" argument instead.'
+        );
+        err.code = 'DISALLOWED_EXTENSION';
+        throw err;
+      }
+      spec = JSON.parse(fs.readFileSync(resolvedSpecPath, 'utf8'));
     }
     const writeBody = { spec };
     if (args.base_file_b64) writeBody.base_file_b64 = args.base_file_b64;
@@ -1135,14 +1435,47 @@ async function dispatchTool(name, args) {
     });
   }
 
+  // xlsx_data_clean: scan + optional execute. Diagnose mode returns
+  // findings only (no file_b64 in _meta). Execute mode returns
+  // cleaned bytes in _meta.file_b64; applyFileB64 saves to out_path
+  // if provided. SPEC fields pass through verbatim — server validates.
+  if (name === 'xlsx_data_clean') {
+    const body = { file_b64: fileToB64(args.file_path) };
+    if (args.mode !== undefined) body.mode = args.mode;
+    if (args.detectors !== undefined) body.detectors = args.detectors;
+    if (args.sheets !== undefined) body.sheets = args.sheets;
+    if (args.options !== undefined) body.options = args.options;
+    if (args.overrides !== undefined) body.overrides = args.overrides;
+    if (args.accept_findings !== undefined) body.accept_findings = args.accept_findings;
+    if (args.reject_findings !== undefined) body.reject_findings = args.reject_findings;
+    const result = await callTool('xlsx_data_clean', body);
+    return applyFileB64(result, args.out_path);
+  }
+
   // xlsx_post_slack: outbound file-to-Slack. Top-level fields, not the
   // standard {file_b64, options} shape — channel + slack_token + message
   // + filename live alongside file_b64 in the server route's body schema.
+  //
+  // Token resolution order (H3 fix):
+  //   1. SLACK_BOT_TOKEN env var (recommended — never enters conversation logs)
+  //   2. slack_token tool arg (legacy; visible in MCP conversation history)
+  // Error if neither is present.
   if (name === 'xlsx_post_slack') {
+    const slackToken = process.env.SLACK_BOT_TOKEN || args.slack_token;
+    if (!slackToken) {
+      const err = new Error(
+        'Slack token required. Set the SLACK_BOT_TOKEN environment variable ' +
+        '(recommended) or pass slack_token as a tool argument.'
+      );
+      err.code = 'MISSING_TOKEN';
+      throw err;
+    }
+    // fileToB64 enforces existence + extension allowlist (H1 fix) — only
+    // spreadsheet extensions (.xlsx, .xlsm, etc.) are permitted here.
     const body = {
       file_b64: fileToB64(args.file_path),
       channel: args.channel,
-      slack_token: args.slack_token,
+      slack_token: slackToken,
     };
     if (args.message !== undefined) body.message = args.message;
     body.filename = args.filename || path.basename(args.file_path);
@@ -1151,12 +1484,28 @@ async function dispatchTool(name, args) {
 
   // xlsx_post_teams: outbound file-to-Teams. Same shape as Slack but with
   // Microsoft Graph fields (team_id + channel_id + graph_token).
+  //
+  // Token resolution order (H3 fix):
+  //   1. TEAMS_GRAPH_TOKEN env var (recommended — never enters conversation logs)
+  //   2. graph_token tool arg (legacy; visible in MCP conversation history)
+  // Error if neither is present.
   if (name === 'xlsx_post_teams') {
+    const graphToken = process.env.TEAMS_GRAPH_TOKEN || args.graph_token;
+    if (!graphToken) {
+      const err = new Error(
+        'Microsoft Graph token required. Set the TEAMS_GRAPH_TOKEN environment variable ' +
+        '(recommended) or pass graph_token as a tool argument.'
+      );
+      err.code = 'MISSING_TOKEN';
+      throw err;
+    }
+    // fileToB64 enforces existence + extension allowlist (H1 fix) — only
+    // spreadsheet extensions (.xlsx, .xlsm, etc.) are permitted here.
     const body = {
       file_b64: fileToB64(args.file_path),
       team_id: args.team_id,
       channel_id: args.channel_id,
-      graph_token: args.graph_token,
+      graph_token: graphToken,
     };
     if (args.message !== undefined) body.message = args.message;
     body.filename = args.filename || path.basename(args.file_path);
@@ -1187,6 +1536,37 @@ async function dispatchTool(name, args) {
     return callTool('xlsx_verify_stamp', body);
   }
 
+  // xlsx_receipt: attach an AI-generation receipt. Server signs caller-
+  // declared agent + optional inputs (source-file hashes, prompt hash,
+  // mcp-tools-called) + optional description; embeds the SignedReceipt in
+  // docProps/custom.xml. Honesty: server signs the STRINGS the caller
+  // supplied; does NOT verify agent identity.
+  if (name === 'xlsx_receipt') {
+    const body = {
+      file_b64: fileToB64(args.file_path),
+      agent: { name: args.agent_name },
+    };
+    if (args.agent_display_name !== undefined) body.agent.display_name = args.agent_display_name;
+    if (args.agent_identity_url !== undefined) body.agent.identity_url = args.agent_identity_url;
+    const inputs = {};
+    if (args.source_file_hashes !== undefined) inputs.source_file_hashes = args.source_file_hashes;
+    if (args.prompt_hash !== undefined) inputs.prompt_hash = args.prompt_hash;
+    if (args.mcp_tools_called !== undefined) inputs.mcp_tools_called = args.mcp_tools_called;
+    if (Object.keys(inputs).length > 0) body.inputs = inputs;
+    if (args.description !== undefined) body.description = args.description;
+    if (args.covers_sheets !== undefined) body.covers_sheets = args.covers_sheets;
+    const result = await callTool('xlsx_receipt', body);
+    return applyFileB64(result, args.out_path);
+  }
+
+  // xlsx_verify_receipt: extract + verify the AI-generation receipt.
+  // Surfaces caller-declared agent.name as declared; no cryptographic
+  // identity binding in v1.
+  if (name === 'xlsx_verify_receipt') {
+    const body = { file_b64: fileToB64(args.file_path) };
+    return callTool('xlsx_verify_receipt', body);
+  }
+
   // All other tools (list_sheets, schema, hyperlinks, conditional_formats,
   // styles, etc.) — single-file relay. Forward any common option keys the
   // routes accept so we don't silently drop them. New keys added here as
@@ -1213,13 +1593,36 @@ 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' };
   }
-  const liveTools = catalog.tools;
+  // Surface catalog source so operators can tell server vs cache vs static
+  // when an MCP session looks "off" (e.g., a tool missing because the remote
+  // /api/v1/tools/list 404'd and we silently fell back to the stale baked-in
+  // set). Stderr only — stdout is the MCP transport.
+  process.stderr.write(`xlsx-for-ai-mcp: tool catalog source=${catalog.source} count=${Array.isArray(catalog.tools) ? catalog.tools.length : 0}\n`);
+  // Overlay MCP annotations (title / readOnlyHint / destructiveHint) so
+  // they flow through to clients regardless of catalog source. The remote
+  // /api/v1/tools/list returns minimal entries today; this is what
+  // restores the annotations the wire format would otherwise drop.
+  const liveTools = applyAnnotations(Array.isArray(catalog.tools) ? catalog.tools : []);
 
   const server = new Server(
     { name: 'xlsx-for-ai', version: require('./package.json').version },
@@ -1247,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,
       };
     }
@@ -1266,5 +1680,9 @@ if (require.main === module) {
   });
 }
 
-// Test-only exports — never import these in production code
-module.exports = { applyFileB64, dispatchTool };
+// Exports for build-time scripts and tests only. Do NOT import these from
+// runtime production code — they're only here to let the manifest-build
+// script use TOOLS as the single source of truth for downstream artifacts
+// (manifest.json, mcp-tools.json snapshot consumed by the MSFT plugin
+// manifest), and to expose helpers under test.
+module.exports = { applyFileB64, dispatchTool, TOOLS };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xlsx-for-ai",
   "mcpName": "io.github.senoff/xlsx-for-ai",
-  "version": "2.23.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": {
@@ -22,7 +22,10 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/v2/*.test.js"
+    "test": "node --test test/v2/*.test.js",
+    "build-manifests": "node scripts/build-manifests.js",
+    "check-manifests": "node scripts/build-manifests.js --check",
+    "prepare": "husky"
   },
   "keywords": [
     "xlsx",
@@ -57,5 +60,8 @@
   },
   "optionalDependencies": {
     "@protobi/exceljs": "^4.4.0-protobi.9"
+  },
+  "devDependencies": {
+    "husky": "^9.1.7"
   }
 }