xlsx-for-ai 2.22.0 → 2.23.0

package/README.md

@@ -196,6 +196,13 @@ For custom MCP clients, the binary is `xlsx-for-ai-mcp` (stdio transport). Overr
 | `xlsx_post_slack` | Post a workbook to a Slack channel as a file attachment with an optional message. BYOA — the agent supplies the user's Slack bot token (`xoxb-…`); the token is forwarded to Slack and never persisted. Uses Slack's external upload flow. |
 | `xlsx_post_teams` | Post a workbook to a Microsoft Teams channel as a file attachment in a channel message, with an optional message. BYOA — the agent supplies the user's Microsoft Graph access token (JWT); the token is forwarded to Microsoft and never persisted. Uses Graph's filesFolder + upload-session + post-message flow. |
 
+### Integrity verification
+
+| Tool | What it does |
+|---|---|
+| `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. |
+
 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.
 
 ---

package/mcp.js

@@ -872,6 +872,56 @@ const TOOLS = [
       required: ['file_path', 'team_id', 'channel_id', 'graph_token'],
     },
   },
+
+  {
+    name: 'xlsx_stamp',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: sign a workbook with a "workbook integrity verification" stamp — a cryptographic attestation embedded in docProps/custom.xml that says "this file was generated by these tools, passed these N specific checks, signed at this time, and hasn\'t been tampered with since." Factual claims only (never an opinion-shaped seal of approval). Returns the stamped workbook as base64 in _meta.file_b64; pass out_path to write to disk.\n' +
+      'The caller supplies the `checks` array (e.g., from a supervisor review): list of named tests, each with passed/failed/skipped status. Verifiers see the individual check results, not a single good/bad opinion.\n\n' +
+      'USE WHEN: the agent has just produced or reviewed a workbook and wants to attach provable provenance + check results that travel with the file. The recipient can later verify the stamp via xlsx_verify_stamp to confirm the file hasn\'t been modified and to see the original check results.\n\n' +
+      'DO NOT USE WHEN: the user just wants to share a file (use xlsx_post_slack / xlsx_post_teams). Or when there are no real checks to attest to (an empty checks array is allowed and means "we ran zero checks" — but the stamp\'s value is in the checks it records).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to stamp.' },
+        checks: {
+          type: 'array',
+          description: 'Array of named checks, each with passed/failed/skipped status. These are the factual claims the stamp attests to.',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', description: 'Stable check identifier (e.g., "tieouts_consistent").' },
+              name: { type: 'string', description: 'Human-readable check name.' },
+              status: { type: 'string', enum: ['passed', 'failed', 'skipped'] },
+              detail: { type: 'string', description: 'Optional explanation, especially for failed/skipped status.' },
+            },
+            required: ['id', 'name', 'status'],
+          },
+        },
+        out_path: { type: 'string', description: 'Optional: write the stamped workbook to this absolute path. If omitted, the stamped bytes are returned in _meta.file_b64 only.' },
+        exclude_sheets: { type: 'array', items: { type: 'string' }, description: 'Optional: sheet names to exclude from the content hash. Use for scratch tabs that legitimately change without affecting attestation.' },
+        supervisor_version: { type: 'string', description: 'Optional: xlsx-supervisor version string to include in the stamp\'s generated_by claim (e.g., "xlsx-supervisor@1.4.0").' },
+      },
+      required: ['file_path', 'checks'],
+    },
+  },
+
+  {
+    name: 'xlsx_verify_stamp',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: verify a workbook\'s embedded integrity-verification stamp. Returns whether the cryptographic signature is valid, whether the workbook bytes match what was signed (recomputed hash vs hash IN the stamp), and the full check-result content of the stamp.\n' +
+      'A workbook can fail verification three ways: (1) no stamp present (file was never stamped, or the stamp was stripped); (2) signature_valid=false (someone modified the claims after signing, or signed with a different key); (3) hash_matches=false (someone modified the workbook bytes after signing). Each is a distinct trust signal.\n\n' +
+      'USE WHEN: the agent (or a downstream verifier) needs to confirm a workbook hasn\'t been tampered with since it was signed, OR needs to surface the original check results that were attested to. Common scenario: incoming workbook from a counterparty, agent runs verify before trusting any of its values.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to verify.' },
+      },
+      required: ['file_path'],
+    },
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -1113,6 +1163,30 @@ async function dispatchTool(name, args) {
     return callTool('xlsx_post_teams', body);
   }
 
+  // xlsx_stamp: sign + embed an integrity-verification stamp. Returns the
+  // stamped file as base64 in _meta.file_b64; if out_path is provided we
+  // also write the bytes to disk (same pattern as xlsx_write / xlsx_redact).
+  if (name === 'xlsx_stamp') {
+    const body = {
+      file_b64: fileToB64(args.file_path),
+      checks: args.checks,
+    };
+    if (args.exclude_sheets !== undefined) body.exclude_sheets = args.exclude_sheets;
+    if (args.supervisor_version !== undefined) {
+      body.generated_by = { npm: 'xlsx-for-ai@' + require('./package.json').version, supervisor: args.supervisor_version };
+    }
+    const result = await callTool('xlsx_stamp', body);
+    return applyFileB64(result, args.out_path);
+  }
+
+  // xlsx_verify_stamp: extract + verify the integrity-verification stamp.
+  // Returns structured result in _meta.{valid, signature_valid, hash_matches,
+  // claims, workbook_hash_in_stamp, workbook_hash_recomputed, …}.
+  if (name === 'xlsx_verify_stamp') {
+    const body = { file_b64: fileToB64(args.file_path) };
+    return callTool('xlsx_verify_stamp', 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xlsx-for-ai",
   "mcpName": "io.github.senoff/xlsx-for-ai",
-  "version": "2.22.0",
+  "version": "2.23.0",
   "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": {