@metamynd/agentsafe-guard 0.6.6 → 0.7.0

package/agentsafe-guard.mjs

@@ -11,6 +11,7 @@
 import crypto from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { evaluate, buildAuthMessage, applySignedLast, operatingModeGate } from './policy-core.mjs';
+import { envelopeHashFor } from './governance-envelope.mjs';
 import { verifyDidSignature } from './magp-did.mjs';
 import { checkSettlementBinding } from './x402.mjs';
 
@@ -120,6 +121,20 @@ export function createGuard(opts = {}) {
     return crypto.sign(null, Buffer.from(message, 'utf8'), privateKey).toString('hex');
   }
 
+  // Tier 1 context-claim binding (opt-in, docs/design/context-claim-binding.md): when
+  // on, sign the GovernanceEnvelope hash too, so a counterparty/gate can prove the
+  // agent's OWN key attested to the context it submitted — not just the signed action
+  // subset. Off by default: a bare request stays a valid degenerate envelope, exactly
+  // like today, and the wire body carries no envelopeSignature field at all.
+  const signContext = opts.signContext ?? cfg?.signContext ?? false;
+  function envelopeSignatureFor({ action, amount, currency, merchant, context, trace, materiality, nonce, issuedAt }) {
+    if (!signContext) return undefined;
+    // The hash is independent of `signature` (excluded from what it commits to — see
+    // governance-envelope.ts), so an empty placeholder here is exact, not approximate.
+    const hash = envelopeHashFor({ agentDid, action, amount, currency, merchant, itinerary: context, trace, materiality, nonce, issuedAt, signature: '' });
+    return sign(hash);
+  }
+
   // --- Enforcement mode (spec §9.2 + local-first plan) --------------------------------------
   // 'local' (DEFAULT): decide the rule layer LOCALLY against a cached signed bundle — a
   //   block/escalate needs no network; an allowed VALUE action is still sealed by the remote
@@ -158,7 +173,11 @@ export function createGuard(opts = {}) {
     const message = buildAuthMessage({ agentDid, action, amount, currency, merchant, nonce, issuedAt });
     // trace/materiality are GovernanceEnvelope fields (SAFR §5) — unsigned metadata; the
     // signed message stays the action subset, so verification is unchanged.
-    return { agentDid, action, amount, currency, merchant, itinerary: context, trace, materiality, nonce, issuedAt, signature: sign(message) };
+    return {
+      agentDid, action, amount, currency, merchant, itinerary: context, trace, materiality, nonce, issuedAt,
+      signature: sign(message),
+      envelopeSignature: envelopeSignatureFor({ action, amount, currency, merchant, context, trace, materiality, nonce, issuedAt }),
+    };
   }
 
   /**
@@ -176,9 +195,14 @@ export function createGuard(opts = {}) {
       const res = await fetch(`${base}/policy/mandate/authorize`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        // trace/materiality (SAFR §5 envelope) ride as unsigned metadata; JSON.stringify
-        // drops them when undefined, so an agent that omits them sends the legacy body.
-        body: JSON.stringify({ agentDid, action, amount, currency, merchant, itinerary: context, trace, materiality, nonce, issuedAt, signature: sign(message) }),
+        // trace/materiality (SAFR §5 envelope) and envelopeSignature (Tier 1, opt-in) ride
+        // as unsigned-message metadata; JSON.stringify drops them when undefined, so an
+        // agent that omits them (or leaves signContext off) sends the legacy body.
+        body: JSON.stringify({
+          agentDid, action, amount, currency, merchant, itinerary: context, trace, materiality, nonce, issuedAt,
+          signature: sign(message),
+          envelopeSignature: envelopeSignatureFor({ action, amount, currency, merchant, context, trace, materiality, nonce, issuedAt }),
+        }),
       });
       const body = await res.json().catch(() => null);
       return body?.data ?? { decision: 'block', reasonCode: `GATE_HTTP_${res.status}` };

package/governance-envelope.mjs

@@ -0,0 +1,69 @@
+// GENERATED from backend/src/features/policy/mandate/governance-envelope.ts — do not edit. Regenerate: npm run build:guard-core
+
+// src/features/policy/mandate/governance-envelope.ts
+import { createHash } from "node:crypto";
+var ENVELOPE_VERSION = "1.0";
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value ?? null);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const obj = value;
+  const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
+}
+function envelopeIntegrityHash(env) {
+  const { integrity: _omit, ...rest } = env;
+  return createHash("sha256").update(stableStringify(rest)).digest("hex");
+}
+function buildGovernanceEnvelope(input) {
+  const base = {
+    envelopeId: `env:${input.nonce}`,
+    version: ENVELOPE_VERSION,
+    createdAt: input.issuedAt,
+    agent: { did: input.agentDid },
+    action: {
+      actionId: `act:${input.nonce}`,
+      actionType: input.action,
+      amount: input.amount,
+      currency: input.currency,
+      merchant: input.merchant ?? null,
+      ...input.materiality ? { materiality: input.materiality } : {}
+    },
+    ...input.trace ? { trace: input.trace } : {},
+    ...input.itinerary ? { context: input.itinerary } : {}
+  };
+  return {
+    ...base,
+    integrity: {
+      payloadHash: envelopeIntegrityHash(base),
+      signature: input.signature,
+      signatureType: "Ed25519"
+    }
+  };
+}
+function envelopeHashFor(input) {
+  return buildGovernanceEnvelope(input).integrity.payloadHash;
+}
+function authorizeInputFromEnvelope(env) {
+  const nonce = env.envelopeId.startsWith("env:") ? env.envelopeId.slice(4) : env.envelopeId;
+  return {
+    agentDid: env.agent.did,
+    action: env.action.actionType,
+    amount: env.action.amount ?? 0,
+    currency: env.action.currency ?? "",
+    merchant: env.action.merchant ?? void 0,
+    itinerary: env.context,
+    trace: env.trace,
+    materiality: env.action.materiality,
+    nonce,
+    issuedAt: env.createdAt,
+    signature: env.integrity.signature ?? ""
+  };
+}
+export {
+  ENVELOPE_VERSION,
+  authorizeInputFromEnvelope,
+  buildGovernanceEnvelope,
+  envelopeHashFor,
+  envelopeIntegrityHash,
+  stableStringify
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-guard",
-  "version": "0.6.6",
+  "version": "0.7.0",
   "description": "Zero-dependency runtime governance for any Node AI agent \u2014 gate tool calls through MetaMynd/AgentSafe (allow / block / escalate) against the agent's mandate, enforced Standards, and SOPs. Ed25519-signed, deterministic, fail-closed.",
   "type": "module",
   "main": "./agentsafe-guard.mjs",
@@ -17,6 +17,7 @@
     "verify.mjs",
     "agentsafe-guard.mjs",
     "policy-core.mjs",
+    "governance-envelope.mjs",
     "magp-did.mjs",
     "x402.mjs",
     "example-openclaw-agent.mjs",
@@ -24,7 +25,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node demo.mjs && node local-eval.smoke.mjs && node execution-adapter.smoke.mjs && node verify.smoke.mjs",
+    "test": "node demo.mjs && node local-eval.smoke.mjs && node execution-adapter.smoke.mjs && node verify.smoke.mjs && node context-signature.smoke.mjs",
     "demo": "node demo.mjs"
   },
   "engines": {