@metamynd/agentsafe-mcp-guard 0.4.0 → 0.6.1

package/README.md

@@ -35,8 +35,8 @@ const guard = createMcpGuard({
 });
 
 // Responder side, over your HTTP transport:
-const challenge = guard.handshakeChallenge(hello);   // POST /magp/handshake  (HELLO → CHALLENGE)
-const ready     = guard.handshakeVerify(prove);      // POST /magp/handshake  (PROVE → READY, or throws)
+const challenge = await guard.handshakeChallenge(hello);  // POST /magp/handshake  (HELLO → CHALLENGE)
+const ready     = guard.handshakeVerify(prove);           // POST /magp/handshake  (PROVE → READY, or throws)
 ```
 
 The agent drives the initiator side with `createGuard(...).handshake()` from `agentsafe-guard`.
@@ -110,6 +110,55 @@ $5,000" protection never engaged, verifier configured or not. New `requireCapabi
 an omitted capability a hard block (`CAPABILITY_REQUIRED`) instead of a silent pass-through. Both
 off by default — existing embeds are unchanged.
 
+**0.5.0 — the `keyProvider` seam
+([docs/design/agent-key-custody-local-signer-daemon-plan.md](../../docs/design/agent-key-custody-local-signer-daemon-plan.md)).**
+`serviceKey` no longer has to be a raw hex key living in this process. Pass
+`keyProvider: 'daemon'` + `daemonSocketPath` instead, and `handshakeChallenge` gets its signature
+from a separate `@metamynd/agentsafe-signer` daemon (`role: 'service'`) over a local socket — the
+key never enters this process at all. `serviceKey` (unchanged) still works exactly as before and
+remains the default. **Breaking, disclosed plainly**: `handshakeChallenge` and
+`createHandshakeInitiator(...).prove()` are now `async` (a daemon-backed provider needs a socket
+round trip); every caller needs an `await` added. New internal module `key-providers.mjs` — still
+zero external dependencies.
+
+**0.5.3 — `requireAuthorization`'s claim now actually enforces revoked authority and mandate
+expiry, and the claim-binding check closes the action axis too.** A four-client readiness review's
+P0 finding required a tested counterparty-verification pattern covering, by name, replay, wrong
+identity, wrong action, expired mandate, and revoked authority. Building the end-to-end trial
+against a real backend (not the mocked cases below) surfaced that two of those five were silently
+unenforced at the claim step itself, not just untested:
+
+- **Revoked authority.** Revoking a mandate (`POST /mandate/:ref/revoke`) only ever flipped the
+  hold's `mandate_event.status` to `voided` — it never touched the `effect_transition` chain, and
+  `markEffect`'s transition check only validated the state-machine shape (`authorized →
+  dispatching` is always syntactically legal), never the hold's own status. A resource relying on
+  `requireAuthorization` could successfully claim and execute a hold whose mandate had already been
+  revoked. Now refused with `AUTHORIZATION_VOIDED`.
+- **Expired mandate.** A hold's expiry (`isWithinHoldWindow`/the TTL) is a *derived* property —
+  nothing writes it back to the row when time passes, so the same claim step had no way to see a
+  hold was stale. Now refused with `AUTHORIZATION_EXPIRED`.
+- **Wrong action.** `claimAuthorization()`'s mismatch checks compared the claimed hold's
+  `agentDid`/`amount`/`currency`/`merchant` against the request being executed, but never `action`
+  — because the backend's claim response never carried it. A real, unclaimed authorization minted
+  for one action (e.g. `office-supplies-purchase`) could be claimed while executing a *different*
+  action at the identical agent/amount/currency/merchant — the same confused-deputy shape the 0.3.6
+  merchant check closed, one axis short. The backend now resolves and returns the hold's authorized
+  `action` on claim (backward-compatible — an older backend simply omits it, same
+  skip-when-absent tolerance as every other field here). Now refused with
+  `AUTHORIZATION_ACTION_MISMATCH`.
+
+All three are backend-side (`MandateService.markEffect`) except the action check, which also
+needed this guard to compare the new field. See
+[`docs/design/mcp-reverification-quickstart.md`](../../docs/design/mcp-reverification-quickstart.md) (§7)
+for the end-to-end trial these gaps were found and closed against.
+
+**0.5.1 — `keyProvider: 'daemon'` retries a transient connect failure.** Same fix as
+`@metamynd/agentsafe-guard` 0.9.1: on Windows the signer daemon's socket is a pool of independent
+named-pipe instances, each consumed by one connection and replaced asynchronously, so two
+signing requests close together could race that replacement window and fail with
+`DAEMON_UNREACHABLE` even though the daemon was healthy. `key-providers.mjs` now retries a
+connection that fails with `ENOENT` for up to 3 seconds before giving up. No API change.
+
 ### Replay, cumulative spend, rate limits, breakers, spend anomalies (`requireAuthorization`)
 
 Re-evaluating policy per request (above) proves the request is well-formed and in-policy — it

package/agentsafe-mcp-guard.mjs

@@ -16,6 +16,7 @@ import { evaluate, buildAuthMessage, applySignedLast, operatingModeGate } from '
 import { verifyDidSignature } from './magp-did.mjs';
 import { buildPaymentRequirements, checkSettlementBinding } from './x402.mjs';
 import { verifyBundle } from './magp-policy.mjs';
+import { resolveKeyProvider } from './key-providers.mjs';
 
 /** Freshness window for signed requests and handshake nonces (spec §7.7). How far `issuedAt`
  *  may be BEHIND server time — network/processing delay. */
@@ -57,19 +58,15 @@ const CLOCK_SKEW_TOLERANCE_MS = 30 * 1000;
  *   integrator's un-capability-aware callers must keep working); set true on any Service where
  *   capability binding is meant to be mandatory, not opt-in.
  */
-export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle, policyPublicKey, settlementStore, verifyCapability, requireAuthorization = false, requireCapability = false } = {}) {
+export function createMcpGuard({ serviceDid, serviceKey, keyProvider: keyProviderOpt, daemonSocketPath, issuerApi, fetchBundle, policyPublicKey, settlementStore, verifyCapability, requireAuthorization = false, requireCapability = false } = {}) {
   if (!serviceDid) throw new Error('createMcpGuard requires { serviceDid }');
   const base = issuerApi ? issuerApi.replace(/\/$/, '') : null;
-  const privateKey = serviceKey
-    ? crypto.createPrivateKey({ key: Buffer.from(serviceKey, 'hex'), format: 'der', type: 'pkcs8' })
-    : null;
+  // keyProvider seam (docs/design/agent-key-custody-local-signer-daemon-plan.md): null when
+  // neither `serviceKey` nor `keyProvider` is configured — handshakeChallenge throws its own
+  // clear error only if actually called, matching the original lazy-throw behavior exactly.
+  const keyProvider = resolveKeyProvider({ keyProvider: keyProviderOpt, serviceKey, daemonSocketPath });
   const pending = new Map(); // handshakeId -> { fromDid, nonceB, expiresAt }
 
-  function sign(message) {
-    if (!privateKey) throw new Error('serviceKey is required to sign handshake messages');
-    return crypto.sign(null, Buffer.from(message, 'utf8'), privateKey).toString('hex');
-  }
-
   // --- Mutual handshake, RESPONDER side (spec §8.2) ---
   //   A → B  HELLO      { fromDid, nonceA }
   //   B → A  CHALLENGE  { toDid, nonceB, sigB(nonceA) }   ← proves B controls toDid
@@ -77,12 +74,13 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
   //   B → A  READY      { channelId }
 
   /** Step 1 (B): on HELLO, sign nonceA to prove control of serviceDid, issue nonceB. */
-  function handshakeChallenge({ fromDid, nonceA, protoVersion } = {}) {
+  async function handshakeChallenge({ fromDid, nonceA, protoVersion } = {}) {
     if (!fromDid || !nonceA) throw new Error('HELLO requires { fromDid, nonceA }');
+    if (!keyProvider) throw new Error('serviceKey (or keyProvider) is required to sign handshake messages');
     const handshakeId = crypto.randomUUID();
     const nonceB = crypto.randomUUID();
     pending.set(handshakeId, { fromDid, nonceB, expiresAt: Date.now() + FRESHNESS_MS });
-    return { handshakeId, toDid: serviceDid, nonceB, sigB: sign(nonceA), protoVersion: protoVersion ?? '1.0' };
+    return { handshakeId, toDid: serviceDid, nonceB, sigB: await keyProvider.signHandshakeNonce(nonceA), protoVersion: protoVersion ?? '1.0' };
   }
 
   /** Step 2 (B): on PROVE, verify sigA over nonceB against fromDid's key-in-DID. */
@@ -110,12 +108,12 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
    * against the stateful issuer gate already checked both (agentsafe-guard.mjs's authorizeLocal()
    * seals any value-bearing action through the real remote authorize() by default).
    *
-   * On success, also returns the hold's OWN bound `agentDid`/`amount`/`currency`/`merchant` — the
-   * caller MUST compare these to the request actually being executed. A claim alone only proves
-   * "some real, unclaimed authorization exists"; without this check, a legitimately-obtained
-   * authorization for a small, honest transaction could be presented to unlock a completely
-   * different one — the same confused-deputy shape payload binding closes at the request layer,
-   * recurring one layer deeper.
+   * On success, also returns the hold's OWN bound `agentDid`/`action`/`amount`/`currency`/
+   * `merchant` — the caller MUST compare these to the request actually being executed. A claim
+   * alone only proves "some real, unclaimed authorization exists"; without this check, a
+   * legitimately-obtained authorization for a small, honest transaction (or a DIFFERENT action
+   * entirely) could be presented to unlock a completely different one — the same confused-deputy
+   * shape payload binding closes at the request layer, recurring one layer deeper.
    */
   async function claimAuthorization({ authorizationId } = {}) {
     if (!authorizationId) return { claimed: false, reasonCode: 'AUTHORIZATION_REQUIRED' };
@@ -124,7 +122,14 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
       const res = await fetch(`${base}/policy/mandate/authorize/${encodeURIComponent(authorizationId)}/effect/dispatching`, { method: 'POST' });
       const body = await res.json().catch(() => null);
       if (!res.ok) return { claimed: false, reasonCode: body?.message ?? body?.data?.reasonCode ?? `AUTHORIZATION_CLAIM_HTTP_${res.status}` };
-      return { claimed: true, agentDid: body?.data?.agentDid, amount: body?.data?.amount, currency: body?.data?.currency, merchant: body?.data?.merchant };
+      return {
+        claimed: true,
+        agentDid: body?.data?.agentDid,
+        action: body?.data?.action,
+        amount: body?.data?.amount,
+        currency: body?.data?.currency,
+        merchant: body?.data?.merchant,
+      };
     } catch (err) {
       return { claimed: false, reasonCode: 'AUTHORIZATION_CLAIM_UNREACHABLE', error: String(err?.message ?? err) };
     }
@@ -253,10 +258,12 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
         // re-open the confused-deputy gap this claim exists to close, and nothing else here
         // would notice.
         if (claim.agentDid === undefined) console.warn('[mcp-guard] claim response omitted agentDid — binding degraded to "some valid unclaimed authorization exists"');
+        if (claim.action === undefined) console.warn('[mcp-guard] claim response omitted action — action binding degraded');
         if (Number(amount) > 0 && claim.amount === undefined) console.warn('[mcp-guard] claim response omitted amount for a value-bearing request — amount binding degraded');
         if (Number(amount) > 0 && claim.currency === undefined) console.warn('[mcp-guard] claim response omitted currency for a value-bearing request — currency binding degraded');
         if (merchant && claim.merchant === undefined) console.warn('[mcp-guard] claim response omitted merchant for a request that signed one — merchant binding degraded');
         if (claim.agentDid !== undefined && claim.agentDid !== agentDid) return { decision: 'block', reasonCode: 'AUTHORIZATION_AGENT_MISMATCH' };
+        if (claim.action !== undefined && claim.action !== action) return { decision: 'block', reasonCode: 'AUTHORIZATION_ACTION_MISMATCH' };
         if (claim.amount !== undefined && Number(claim.amount) !== Number(amount)) return { decision: 'block', reasonCode: 'AUTHORIZATION_AMOUNT_MISMATCH' };
         if (claim.currency !== undefined && claim.currency !== currency) return { decision: 'block', reasonCode: 'AUTHORIZATION_CURRENCY_MISMATCH' };
         if (claim.merchant !== undefined && claim.merchant !== merchant) return { decision: 'block', reasonCode: 'AUTHORIZATION_MERCHANT_MISMATCH' };
@@ -274,7 +281,17 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
    */
   function guardIncomingTool(action, handler) {
     return async (signed, ...rest) => {
-      const decision = await verifyRequest({ ...signed, action: signed?.action ?? action });
+      // The WRAPPED TOOL's own `action` is authoritative — never `signed?.action` (the caller's
+      // own claim). A Service that wraps more than one tool with ONE guard instance (the normal
+      // MCP-server shape: many tools, one guard) previously let a genuinely-valid signature for
+      // action A verify successfully — correctly, it really was valid for A — and then run
+      // action B's handler, because verifyRequest was asked to check whatever the SIGNED payload
+      // claimed instead of which wrapped function was actually being invoked. A caller with a
+      // real, cheap, in-policy authorization (e.g. a $0 read) could invoke ANY other tool sharing
+      // this guard (e.g. a wire transfer) and have it execute under that unrelated verification.
+      // Mirrors gateway.mjs's `route.action ?? signed.action` — "the route pins the action ...
+      // the client can't pick it" — for exactly the same reason, one layer down at the tool call.
+      const decision = await verifyRequest({ ...signed, action });
       // allow/observe both PERMIT the tool call; observe is permit-but-flag (SAFR §11).
       if (decision.decision !== 'allow' && decision.decision !== 'observe') {
         const err = new Error(`MCP guard ${decision.decision.toUpperCase()} "${action}": ${decision.reasonCode}`);
@@ -389,7 +406,9 @@ export function createMcpGuard({ serviceDid, serviceKey, issuerApi, fetchBundle,
  * then, given the responder's CHALLENGE, verifies the responder proved control of
  * its DID before producing PROVE.
  *
- * @param {{fromDid:string, sign:(msg:string)=>string}} p  sign() uses the initiator's own key
+ * @param {{fromDid:string, sign:(msg:string)=>(string|Promise<string>)}} p  sign() uses the
+ *   initiator's own key — may be sync (a raw local key) or async (e.g. a keyProvider backed by
+ *   agentsafe-signer); `prove()` awaits it either way, see key-providers.mjs.
  */
 export function createHandshakeInitiator({ fromDid, sign } = {}) {
   if (!fromDid || typeof sign !== 'function') throw new Error('createHandshakeInitiator requires { fromDid, sign }');
@@ -400,7 +419,7 @@ export function createHandshakeInitiator({ fromDid, sign } = {}) {
       return { nonceA, message: { fromDid, nonceA, protoVersion: '1.0' } };
     },
     /** Step 3 (A): verify CHALLENGE proves the responder controls toDid, then PROVE. */
-    prove({ nonceA, challenge } = {}) {
+    async prove({ nonceA, challenge } = {}) {
       const { toDid, nonceB, sigB, handshakeId } = challenge ?? {};
       if (!toDid || !nonceB || !sigB) throw new Error('malformed CHALLENGE');
       if (!verifyDidSignature(toDid, nonceA, sigB)) {
@@ -408,7 +427,7 @@ export function createHandshakeInitiator({ fromDid, sign } = {}) {
         e.name = 'HandshakeFailed';
         throw e;
       }
-      return { handshakeId, sigA: sign(nonceB), remoteDid: toDid };
+      return { handshakeId, sigA: await sign(nonceB), remoteDid: toDid };
     },
   };
 }

package/key-providers.mjs

@@ -0,0 +1,91 @@
+// key-providers.mjs — the keyProvider seam for the SERVICE side (docs/design/
+// agent-key-custody-local-signer-daemon-plan.md). Much smaller than agentsafe-guard's own copy:
+// serviceKey is only ever used for one thing (signing a handshake nonce, MAGP §8.2), so there is
+// only one provider method here, not four.
+import crypto from 'node:crypto';
+import net from 'node:net';
+import path from 'node:path';
+
+export function createStaticKeyProvider(serviceKeyHex) {
+  const privateKey = crypto.createPrivateKey({ key: Buffer.from(serviceKeyHex, 'hex'), format: 'der', type: 'pkcs8' });
+  return {
+    async signHandshakeNonce(nonce) {
+      return crypto.sign(null, Buffer.from(nonce, 'utf8'), privateKey).toString('hex');
+    },
+  };
+}
+
+/** Must match agentsafe-guard/key-providers.mjs's and agentsafe-signer/daemon.mjs's own copy — see either's own comment for why this isn't a shared import. */
+function toPlatformSocketPath(logicalPath) {
+  if (process.platform !== 'win32') return logicalPath;
+  const name = crypto.createHash('sha256').update(path.resolve(logicalPath)).digest('hex').slice(0, 32);
+  return `\\\\.\\pipe\\agentsafe-signer-${name}`;
+}
+
+const PROTOCOL_VERSION = 1;
+
+function daemonRequest(socketPath, op, params, { connectTimeoutMs = 3000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + connectTimeoutMs;
+    function attempt() {
+      const sock = net.connect(toPlatformSocketPath(socketPath));
+      const requestId = crypto.randomUUID();
+      let buf = '';
+      const cleanup = () => sock.destroy();
+      sock.once('error', (err) => {
+        cleanup();
+        // See agentsafe-guard/key-providers.mjs's own copy of this function for why: on Windows
+        // the signing socket is a pool of independent named-pipe instances, each consumed by one
+        // connection and replaced asynchronously, so a request can transiently race that
+        // replacement window (ENOENT) even though the daemon is healthy. Only ENOENT retries — a
+        // genuinely down daemon still fails fast.
+        if (err.code === 'ENOENT' && Date.now() < deadline) {
+          setTimeout(attempt, 20);
+          return;
+        }
+        reject(Object.assign(new Error(`agentsafe-signer daemon unreachable at ${socketPath}: ${err.message}`), { code: 'DAEMON_UNREACHABLE' }));
+      });
+      sock.once('connect', () => {
+        sock.write(JSON.stringify({ protocolVersion: PROTOCOL_VERSION, requestId, op, params }) + '\n');
+      });
+      sock.on('data', (chunk) => {
+        buf += chunk.toString('utf8');
+        const idx = buf.indexOf('\n');
+        if (idx === -1) return;
+        let res;
+        try {
+          res = JSON.parse(buf.slice(0, idx));
+        } catch (err) {
+          cleanup();
+          reject(err);
+          return;
+        }
+        cleanup();
+        if (res.ok) resolve(res.result);
+        else reject(Object.assign(new Error(res.error?.message || res.error?.code || 'daemon rejected request'), { code: res.error?.code }));
+      });
+    }
+    attempt();
+  });
+}
+
+/** The key never enters this process — a service-role agentsafe-signer daemon signs instead. */
+export function createDaemonKeyProvider({ socketPath }) {
+  if (!socketPath) throw new Error('createDaemonKeyProvider requires { socketPath }');
+  return {
+    async signHandshakeNonce(nonce) {
+      const { signature } = await daemonRequest(socketPath, 'sign-handshake-nonce', { nonce });
+      return signature;
+    },
+  };
+}
+
+/** Resolves a keyProvider from createMcpGuard's opts — null (not thrown) when neither
+ *  keyProvider nor serviceKey is configured, matching today's "handshakeChallenge throws only if
+ *  actually called without one" behavior rather than failing construction eagerly. */
+export function resolveKeyProvider({ keyProvider, serviceKey, daemonSocketPath } = {}) {
+  if (keyProvider && typeof keyProvider === 'object' && typeof keyProvider.signHandshakeNonce === 'function') return keyProvider;
+  if (keyProvider === 'daemon') return createDaemonKeyProvider({ socketPath: daemonSocketPath });
+  if (!serviceKey) return null;
+  return createStaticKeyProvider(serviceKey);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-mcp-guard",
-  "version": "0.4.0",
+  "version": "0.6.1",
   "description": "Zero-dependency trustless governance for the SERVICE side. An MCP server or API re-verifies a calling agent's signed request against the agent's own published policy \u00e2\u20ac\u201d so an agent that ignores its own guard still cannot make your service act.",
   "type": "module",
   "main": "./agentsafe-mcp-guard.mjs",
@@ -15,6 +15,7 @@
   },
   "files": [
     "agentsafe-mcp-guard.mjs",
+    "key-providers.mjs",
     "magp-policy.mjs",
     "magp-did.mjs",
     "policy-core.mjs",
@@ -23,7 +24,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node mcp-guard.smoke.mjs && node pay.smoke.mjs && node decision-token.smoke.mjs && node claim-authorization.smoke.mjs"
+    "test": "node mcp-guard.smoke.mjs && node pay.smoke.mjs && node decision-token.smoke.mjs && node claim-authorization.smoke.mjs && node guard-incoming-tool.smoke.mjs"
   },
   "engines": {
     "node": ">=18"

package/policy-core.mjs

@@ -514,7 +514,15 @@ function escapeField(v) {
   return v.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
 }
 function buildAuthMessage(f) {
-  return [f.agentDid, f.action, f.amount, f.currency, f.merchant ?? "", f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
+  return [f.agentDid, f.action, f.amount, f.currency, f.merchant ?? "", f.resource ?? "", f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
+}
+function buildLocalDecisionMessage(f) {
+  return [f.agentDid, f.action, f.decision, f.reasonCode, f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
+}
+
+// src/policy-core/checkpoint-anchor.ts
+function buildCheckpointAnchorMessage(f) {
+  return [f.agentDid, f.checkpointHash, f.previousCheckpointHash, f.entryCount, f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
 }
 
 // src/policy-core/context.ts
@@ -573,6 +581,8 @@ export {
   asOperatingMode,
   authorityFailure,
   buildAuthMessage,
+  buildCheckpointAnchorMessage,
+  buildLocalDecisionMessage,
   canAuthorize,
   evaluate,
   evaluateBoundStandards,