@odingard/guardian-mcp 0.3.4 → 0.4.0

package/README.md

@@ -120,6 +120,23 @@ upstream server's tools unchanged, and every call is decided first:
 `guardian-mcp --help` prints usage. A missing setting prints a one-line
 message naming it instead of a stack trace.
 
+### Pin the contents of file arguments: `--pin-file` (0.4)
+
+Approval binds the exact arguments. A file path is an argument; the file's contents are not, unless you declare the argument with `--pin-file`.
+
+```bash
+guardian-mcp proxy --pin-file upload_file:path --pin-file send_email:attachment -- npx -y my-mcp-server
+```
+
+For each declared `<tool>:<argument>` the proxy (the SDK on your machine) reads the file the path names, puts its SHA-256 in the approved arguments, and checks it again just before the call is forwarded. Guardian's servers never see the file. If the file changed, nothing is forwarded, the capability is not redeemed, and the result says `CONTENT_CHANGED_SINCE_APPROVAL`; propose the call again for a new approval. A call held for approval keeps the arguments that were proposed, pins included, and `guardian_claim` checks the file against them. After a proxy restart a claim finds nothing; call the tool again, which pins the file again. The upstream server receives the approved arguments without the reserved key `guardianContentPins`. In code: `createGovernedProxy({ ..., pinFiles: { upload_file: ["path"] } })`.
+
+- The mode is always `recheck`: the upstream server opens the path itself, so a short window remains between the check and its open.
+- Stdio upstreams only. With `--url` (HTTP or SSE) the path names a file on another machine, so `--pin-file` is refused at start (`CONTENT_PIN_REMOTE_UPSTREAM`). Paths on a remote MCP server are not pinned.
+- File paths must be absolute. The proxy does not resolve relative paths or `~`.
+- Content pinning is supported on Linux and macOS. On Windows a declared file argument is refused (`CONTENT_PIN_UNSUPPORTED_PLATFORM`).
+- **Digest privacy:** the SHA-256 of each pinned file is sent to Guardian, shown to the approver and kept in receipts. For a small or low-entropy file (a token, a PIN, a short config value), anyone who sees the digest can guess the contents offline by hashing candidates. Do not pin files like that, or treat the digest as sensitive as the file.
+- This stops a changed file from running under an approval given for different contents. It does not protect against code that bypasses the proxy, and files a tool opens without naming them in a declared argument are not pinned.
+
 ## Govern a remote MCP server: `guardian-mcp proxy --url` (0.3.3 and later)
 
 **Status: tested against a real Guardian; production proof pending.** It ran

package/dist/index.js

@@ -16,6 +16,11 @@ var USAGE = `guardian-mcp \u2014 route an agent's tool calls through Guardian (A
 Usage:
   guardian-mcp                               Guardian tools (guardian_invoke_tool, guardian_claim, guardian_receipt)
   guardian-mcp proxy -- <command> [args...]  Govern every tool of an existing stdio MCP server
+  guardian-mcp proxy --pin-file <tool>:<arg> [--pin-file ...] -- <command> [args...]
+                                             Also pin the file a path argument names: its SHA-256
+                                             goes into the approved arguments and is checked again
+                                             just before the call is forwarded (stdio upstreams
+                                             only; the path must be absolute)
   guardian-mcp proxy --url <https-url> [--transport streamable-http|sse] [--header "Name: value"]...
                                              Govern every tool of a remote MCP server (Streamable
                                              HTTP by default, or SSE). The agent still talks stdio.
@@ -64,9 +69,24 @@ function parseCli(argv, env) {
     };
   }
   if (argv[0] === "proxy") {
-    const target = parseTarget("proxy", argv.slice(1), env);
+    const pins = extractPinFiles(argv.slice(1));
+    if (!pins.ok) return pins;
+    const target = parseTarget("proxy", pins.rest, env);
     if (!target.ok) return target;
-    mode = { kind: "proxy", ...target.target };
+    const declared = Object.keys(pins.pinFiles).length > 0;
+    if (declared && "remote" in target.target) {
+      return {
+        ok: false,
+        message: `guardian-mcp proxy: --pin-file is supported only for a stdio upstream (CONTENT_PIN_REMOTE_UPSTREAM). A remote MCP server opens paths on another machine, so the proxy cannot check the file it will read.
+
+${USAGE}`
+      };
+    }
+    mode = {
+      kind: "proxy",
+      ...target.target,
+      ...declared ? { pinFiles: pins.pinFiles } : {}
+    };
   } else if (argv.length > 0) {
     return {
       ok: false,
@@ -135,6 +155,42 @@ function expandEnv(cmd, value, env, where) {
     value: value.replace(ENV_REF, (_, name) => env[name])
   };
 }
+function extractPinFiles(argv) {
+  const pinFiles = {};
+  const rest = [];
+  const fail = (message) => ({
+    ok: false,
+    message: `guardian-mcp proxy: ${message}
+
+${USAGE}`
+  });
+  let i = 0;
+  for (; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") break;
+    let value;
+    if (arg === "--pin-file") {
+      value = argv[++i];
+    } else if (arg.startsWith("--pin-file=")) {
+      value = arg.slice("--pin-file=".length);
+    } else {
+      rest.push(arg);
+      continue;
+    }
+    const colon = value?.lastIndexOf(":") ?? -1;
+    const tool = colon > 0 ? value.slice(0, colon) : "";
+    const name = colon > 0 ? value.slice(colon + 1) : "";
+    if (!tool || !name || name.includes(".")) {
+      return fail(
+        '--pin-file needs "<tool>:<argument>", naming a top-level argument.'
+      );
+    }
+    const list = pinFiles[tool] ??= [];
+    if (!list.includes(name)) list.push(name);
+  }
+  rest.push(...argv.slice(i));
+  return { ok: true, pinFiles, rest };
+}
 function parseTarget(cmd, argv, env) {
   const fail = (message) => ({
     ok: false,
@@ -621,6 +677,8 @@ function renderSuggestions(serverCommand, tools, remote = false) {
 
 // src/proxy.ts
 import {
+  CONTENT_PIN_KEY,
+  CONTENT_PIN_REMOTE_UPSTREAM,
   createGuardianContext,
   runThroughGuardian,
   settle,
@@ -629,6 +687,24 @@ import {
   GuardianExecutionFailed,
   GuardianRecordTransportRequired
 } from "@odingard/guardian-sdk";
+var ContentPinConfigError = class extends Error {
+  constructor(reasonCode, message) {
+    super(message);
+    this.reasonCode = reasonCode;
+    this.name = "ContentPinConfigError";
+  }
+  reasonCode;
+};
+function pinFilesToFileArgs(pinFiles) {
+  const fileArgs = {};
+  for (const [toolName, args] of Object.entries(pinFiles ?? {})) {
+    if (args.length === 0) continue;
+    fileArgs[toolName] = Object.fromEntries(
+      args.map((arg) => [arg, "recheck"])
+    );
+  }
+  return fileArgs;
+}
 var CLAIM_TOOL = "guardian_claim";
 var RECEIPT_TOOL = "guardian_receipt";
 var GUARDIAN_RESULT_META = "com.odingard/guardian";
@@ -710,8 +786,14 @@ var UpstreamListFailed = class extends Error {
     this.name = "UpstreamListFailed";
   }
 };
-function callUpstream(upstream, name, args, signal, forwarding) {
-  return async () => {
+function forwardable(approved) {
+  const record = approved !== null && typeof approved === "object" && !Array.isArray(approved) ? { ...approved } : {};
+  delete record[CONTENT_PIN_KEY];
+  return record;
+}
+function callUpstream(upstream, name, signal, forwarding) {
+  return async (approved) => {
+    const args = forwardable(approved);
     if (signal?.aborted) {
       throw new UpstreamCallCancelled(name);
     }
@@ -758,6 +840,19 @@ function failure(err, toolName, forwarding) {
       true
     );
   }
+  if (err instanceof GuardianExecutionFailed && !err.localEffectRan && (err.reasonCode === "CONTENT_CHANGED_SINCE_APPROVAL" || err.reasonCode.startsWith("CONTENT_PIN_"))) {
+    return jsonResult2(
+      {
+        decision: "ALLOW",
+        toolName,
+        requestId: err.requestId,
+        executionFailed: err.reasonCode,
+        localEffectRan: false,
+        message: err.reasonCode === "CONTENT_CHANGED_SINCE_APPROVAL" ? "A file named in the approved call changed since it was approved. Nothing was forwarded and the capability was not redeemed. Propose the call again; it needs a new approval." : "A file named in the approved call could not be checked against its approval. Nothing was forwarded and the capability was not redeemed."
+      },
+      true
+    );
+  }
   if (err instanceof GuardianExecutionFailed) {
     return jsonResult2(
       {
@@ -809,6 +904,13 @@ var CLAIMED_REQUESTS_LIMIT = 1e3;
 function createGovernedProxy(options) {
   const { upstream, log = () => {
   } } = options;
+  const fileArgs = pinFilesToFileArgs(options.pinFiles);
+  if (Object.keys(fileArgs).length > 0 && options.upstreamTransport === "remote") {
+    throw new ContentPinConfigError(
+      CONTENT_PIN_REMOTE_UPSTREAM,
+      "guardian-mcp proxy: --pin-file is supported only for a stdio upstream. A remote (HTTP/SSE) MCP server opens paths on another machine, so the proxy cannot check the file it will read."
+    );
+  }
   const toolInvokeRequestIds = /* @__PURE__ */ new Set();
   const pendingCalls = /* @__PURE__ */ new Map();
   const pendingInstalls = /* @__PURE__ */ new Map();
@@ -841,9 +943,11 @@ function createGovernedProxy(options) {
     onDeny: "result",
     installRecordTransport: options.autoRegister ?? false,
     ...options.adapterId ? { adapterId: options.adapterId } : {},
-    ...options.agentName ? { agentName: options.agentName } : {}
+    ...options.agentName ? { agentName: options.agentName } : {},
+    ...Object.keys(fileArgs).length > 0 ? { fileArgs } : {}
   });
   ctx.installed ??= /* @__PURE__ */ new Set();
+  ctx.proposedInputs = /* @__PURE__ */ new Map();
   function heldSetupStep(toolName, requestId) {
     const held = ctx.heldSetup?.get(`${options.connectionId}:${toolName}`);
     return held?.requestId === requestId ? held.step : void 0;
@@ -895,7 +999,9 @@ function createGovernedProxy(options) {
     const g = output.guardian;
     if (g.decision === "ASK") {
       if (toolInvokeRequestIds.has(g.requestId)) {
-        pendingCalls.set(g.requestId, { name: toolName, args });
+        const proposed = ctx.proposedInputs?.get(g.requestId) ?? args;
+        ctx.proposedInputs?.delete(g.requestId);
+        pendingCalls.set(g.requestId, { name: toolName, args, proposed });
         return jsonResult2({
           decision: "ASK",
           toolName,
@@ -1004,9 +1110,9 @@ function createGovernedProxy(options) {
         const output = await settle(
           call.ctx,
           held.name,
-          held.args,
+          held.proposed,
           claimed,
-          callUpstream(upstream, held.name, held.args, signal, forwarding)
+          callUpstream(upstream, held.name, signal, forwarding)
         );
         result = toCallResult(
           held.name,
@@ -1176,7 +1282,7 @@ function createGovernedProxy(options) {
           call.ctx,
           name,
           args,
-          callUpstream(upstream, name, args, signal, forwarding)
+          callUpstream(upstream, name, signal, forwarding)
         );
         return toCallResult(name, args, output, call.allowedRequestId());
       } catch (err) {
@@ -1315,15 +1421,28 @@ if (config.mode.kind === "proxy") {
     name: "guardian-mcp-proxy",
     version: VERSION
   });
-  const proxy = createGovernedProxy({
-    client,
-    connectionId: config.connectionId,
-    autoRegister: config.autoRegister,
-    ...config.adapterId ? { adapterId: config.adapterId } : {},
-    log: (message) => process.stderr.write(`${message}
+  let proxy;
+  try {
+    proxy = createGovernedProxy({
+      client,
+      connectionId: config.connectionId,
+      autoRegister: config.autoRegister,
+      upstreamTransport: "remote" in config.mode ? "remote" : "stdio",
+      ...config.mode.pinFiles ? { pinFiles: config.mode.pinFiles } : {},
+      ...config.adapterId ? { adapterId: config.adapterId } : {},
+      log: (message) => process.stderr.write(`${message}
 `),
-    upstream: clientUpstream(upstreamClient)
-  });
+      upstream: clientUpstream(upstreamClient)
+    });
+  } catch (err) {
+    process.stderr.write(
+      `${err instanceof Error ? err.message : "guardian-mcp proxy: invalid configuration."}
+`
+    );
+    await upstreamClient.close().catch(() => {
+    });
+    process.exit(2);
+  }
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: await proxy.listTools()
   }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odingard/guardian-mcp",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "mcpName": "io.github.Odingard/guardian-mcp",
   "description": "MCP server that routes an agent's tool calls through Guardian — the human authority layer for autonomous AI. Every tool call gets a deterministic ALLOW/ASK/DENY decision before anything executes; ASK holds for human approval, DENY never runs, and every allowed call that completes carries a verifiable receipt.",
   "license": "Apache-2.0",
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.2",
-    "@odingard/guardian-sdk": "^0.3.9"
+    "@odingard/guardian-sdk": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22",

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
   "name": "io.github.Odingard/guardian-mcp",
   "description": "Routes agent tool calls through Guardian for ALLOW/ASK/DENY before execution.",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "tools": [
     {
       "name": "guardian_invoke_tool",
@@ -26,7 +26,7 @@
     {
       "registryType": "npm",
       "identifier": "@odingard/guardian-mcp",
-      "version": "0.3.4",
+      "version": "0.4.0",
       "transport": {
         "type": "stdio"
       },