@metamynd/agentsafe-guard 0.1.0 → 0.1.2

package/example-openclaw-agent.mjs

@@ -1,47 +1,47 @@
-// example-openclaw-agent.mjs — a runnable demo of the guard against a seeded bound agent.
-//
-// Simulates how an OpenClaw agent's TOOL is wrapped: the raw tool only runs if the
-// AgentSafe gate returns `allow`. Run it after seeding an agent with
-// backend/scripts/demo-seed-governance.ts:
-//
-//   $env:AGENTSAFE_API="http://localhost:9926/api/v1"
-//   $env:AGENT_DID="did:hedera:testnet:..."
-//   $env:AGENT_KEY="302e0201..."
-//   node example-openclaw-agent.mjs
-import { createGuard } from './agentsafe-guard.mjs';
-
-const guard = createGuard({
-  api: process.env.AGENTSAFE_API ?? 'http://localhost:9926/api/v1',
-  agentDid: process.env.AGENT_DID,
-  agentKey: process.env.AGENT_KEY,
-});
-
-// --- The agent's tool. In OpenClaw you register this handler for the tool; here we
-//     wrap it with guard.guardTool so every call is gated first. ---
-const bookFlight = guard.guardTool(
-  'flight-purchase', // the governed action (matches the mandate scope)
-  async (args, decision) => {
-    // Only reached when the gate ALLOWED. Real booking would go here.
-    return { booked: true, pnr: 'PNR-DEMO', remaining: decision.remaining, ...args };
-  },
-  // Map the tool args → gate inputs. `context` carries what the Standard/SOP rules need.
-  (a) => ({ amount: a.amount, currency: 'USD', merchant: a.merchant, context: { tool: a.tool ?? 'book-flight', riskLevel: a.riskLevel ?? 'low' } }),
-);
-
-async function ask(label, args) {
-  try {
-    const r = await bookFlight(args);
-    console.log(`  \x1b[32m✅ ALLOW\x1b[0m   ${label.padEnd(30)} → booked ${r.pnr} (remaining $${r.remaining})`);
-  } catch (e) {
-    const g = e.governance ?? {};
-    const tag = g.decision === 'escalate' ? '\x1b[33m⚠ ESCALATE\x1b[0m' : '\x1b[31m⛔ BLOCK\x1b[0m';
-    console.log(`  ${tag} ${label.padEnd(30)} → ${g.reasonCode ?? e.message}`);
-  }
-}
-
-console.log(`\n  OpenClaw agent — every booking passes through the AgentSafe gate\n  ${'─'.repeat(60)}`);
-await ask('$150 book-flight, low risk', { amount: 150, merchant: 'skyward-air', tool: 'book-flight', riskLevel: 'low' });
-await ask('$600 book-flight', { amount: 600, merchant: 'skyward-air', tool: 'book-flight', riskLevel: 'low' });
-await ask('$100 wire-transfer tool', { amount: 100, merchant: 'skyward-air', tool: 'wire-transfer', riskLevel: 'low' });
-await ask('$100 high-risk decision', { amount: 100, merchant: 'skyward-air', tool: 'book-flight', riskLevel: 'high' });
-console.log(`\n  The agent refuses blocked/escalated actions itself — governance decided, not the LLM.\n`);
+// example-openclaw-agent.mjs — a runnable demo of the guard against a seeded bound agent.
+//
+// Simulates how an OpenClaw agent's TOOL is wrapped: the raw tool only runs if the
+// AgentSafe gate returns `allow`. Run it after seeding an agent with
+// backend/scripts/demo-seed-governance.ts:
+//
+//   $env:AGENTSAFE_API="http://localhost:9926/api/v1"
+//   $env:AGENT_DID="did:hedera:testnet:..."
+//   $env:AGENT_KEY="302e0201..."
+//   node example-openclaw-agent.mjs
+import { createGuard } from './agentsafe-guard.mjs';
+
+const guard = createGuard({
+  api: process.env.AGENTSAFE_API ?? 'http://localhost:9926/api/v1',
+  agentDid: process.env.AGENT_DID,
+  agentKey: process.env.AGENT_KEY,
+});
+
+// --- The agent's tool. In OpenClaw you register this handler for the tool; here we
+//     wrap it with guard.guardTool so every call is gated first. ---
+const bookFlight = guard.guardTool(
+  'flight-purchase', // the governed action (matches the mandate scope)
+  async (args, decision) => {
+    // Only reached when the gate ALLOWED. Real booking would go here.
+    return { booked: true, pnr: 'PNR-DEMO', remaining: decision.remaining, ...args };
+  },
+  // Map the tool args → gate inputs. `context` carries what the Standard/SOP rules need.
+  (a) => ({ amount: a.amount, currency: 'USD', merchant: a.merchant, context: { tool: a.tool ?? 'book-flight', riskLevel: a.riskLevel ?? 'low' } }),
+);
+
+async function ask(label, args) {
+  try {
+    const r = await bookFlight(args);
+    console.log(`  \x1b[32m✅ ALLOW\x1b[0m   ${label.padEnd(30)} → booked ${r.pnr} (remaining $${r.remaining})`);
+  } catch (e) {
+    const g = e.governance ?? {};
+    const tag = g.decision === 'escalate' ? '\x1b[33m⚠ ESCALATE\x1b[0m' : '\x1b[31m⛔ BLOCK\x1b[0m';
+    console.log(`  ${tag} ${label.padEnd(30)} → ${g.reasonCode ?? e.message}`);
+  }
+}
+
+console.log(`\n  OpenClaw agent — every booking passes through the AgentSafe gate\n  ${'─'.repeat(60)}`);
+await ask('$150 book-flight, low risk', { amount: 150, merchant: 'skyward-air', tool: 'book-flight', riskLevel: 'low' });
+await ask('$600 book-flight', { amount: 600, merchant: 'skyward-air', tool: 'book-flight', riskLevel: 'low' });
+await ask('$100 wire-transfer tool', { amount: 100, merchant: 'skyward-air', tool: 'wire-transfer', riskLevel: 'low' });
+await ask('$100 high-risk decision', { amount: 100, merchant: 'skyward-air', tool: 'book-flight', riskLevel: 'high' });
+console.log(`\n  The agent refuses blocked/escalated actions itself — governance decided, not the LLM.\n`);

package/magp-did.mjs

@@ -67,6 +67,30 @@ function parseHederaDid(did) {
   if (publicKeyBytes.length !== 32) return null;
   return { network, publicKeyMultibase, publicKeyBytes, topicId };
 }
+var ED25519_MULTICODEC = Uint8Array.of(237, 1);
+function buildDidKey(publicKeyBytes) {
+  const prefixed = new Uint8Array(ED25519_MULTICODEC.length + publicKeyBytes.length);
+  prefixed.set(ED25519_MULTICODEC, 0);
+  prefixed.set(publicKeyBytes, ED25519_MULTICODEC.length);
+  return `did:key:${multibaseBase58btc(prefixed)}`;
+}
+function parseDidKey(did) {
+  const m = /^did:key:(z[1-9A-HJ-NP-Za-km-z]+)$/.exec(did ?? "");
+  if (!m) return null;
+  const multibase = m[1];
+  let decoded;
+  try {
+    decoded = base58Decode(multibase.slice(1));
+  } catch {
+    return null;
+  }
+  if (decoded.length !== ED25519_MULTICODEC.length + 32) return null;
+  if (decoded[0] !== ED25519_MULTICODEC[0] || decoded[1] !== ED25519_MULTICODEC[1]) return null;
+  return { method: "key", publicKeyMultibase: multibase, publicKeyBytes: decoded.slice(ED25519_MULTICODEC.length) };
+}
+function didPublicKeyBytes(did) {
+  return parseHederaDid(did)?.publicKeyBytes ?? parseDidKey(did)?.publicKeyBytes ?? null;
+}
 
 // src/features/magp/did.ts
 var ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
@@ -75,31 +99,35 @@ function ed25519KeyFromRaw(raw) {
   return crypto.createPublicKey({ key: der, format: "der", type: "spki" });
 }
 function verifyDidSignature(did, message, signatureHex) {
-  const parsed = parseHederaDid(did);
-  if (!parsed) return false;
+  const publicKeyBytes = didPublicKeyBytes(did);
+  if (!publicKeyBytes) return false;
   try {
-    const key = ed25519KeyFromRaw(parsed.publicKeyBytes);
+    const key = ed25519KeyFromRaw(publicKeyBytes);
     return crypto.verify(null, Buffer.from(message, "utf8"), key, Buffer.from(signatureHex, "hex"));
   } catch {
     return false;
   }
 }
 function buildDidDocument(did, service) {
-  const parsed = parseHederaDid(did);
-  if (!parsed) return null;
+  const hedera = parseHederaDid(did);
+  const key = hedera ? null : parseDidKey(did);
+  if (!hedera && !key) return null;
+  const publicKeyMultibase = hedera ? hedera.publicKeyMultibase : key.publicKeyMultibase;
+  const fragment = hedera ? "#did-root-key" : `#${key.publicKeyMultibase}`;
+  const vmId = `${did}${fragment}`;
   const doc = {
     "@context": ["https://www.w3.org/ns/did/v1"],
     id: did,
     controller: did,
     verificationMethod: [
       {
-        id: `${did}#did-root-key`,
+        id: vmId,
         type: "Ed25519VerificationKey2020",
         controller: did,
-        publicKeyMultibase: parsed.publicKeyMultibase
+        publicKeyMultibase
       }
     ],
-    authentication: [`${did}#did-root-key`]
+    authentication: [vmId]
   };
   if (service) {
     doc.service = [
@@ -118,9 +146,12 @@ export {
   base58,
   base58Decode,
   buildDidDocument,
+  buildDidKey,
   buildHederaDid,
+  didPublicKeyBytes,
   ed25519KeyFromRaw,
   multibaseBase58btc,
+  parseDidKey,
   parseHederaDid,
   verifyDidSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-guard",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Zero-dependency runtime governance for any Node AI agent — 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",

package/policy-core.mjs

@@ -11,6 +11,9 @@ var ATOM_REGISTRY = {
     return have !== void 0 && need !== void 0 && have >= need;
   },
   "amount-over": (c, cfg) => typeof c.amount === "number" && c.amount > Number(cfg?.limit ?? 0),
+  // Total budget: cumulativeSpend is a SERVER-derived, signed-last context field (never
+  // shadowable by the agent's itinerary), so this compares already-spent + this amount.
+  "cumulative-over": (c, cfg) => Number(c.cumulativeSpend ?? 0) + Number(c.amount ?? 0) > Number(cfg?.limit ?? 0),
   // Fires if any configured term appears in the prompt and/or output text.
   // Used to govern agent responses on content (prohibited claims, sensitive advice).
   "text-matches": (c, cfg) => {
@@ -27,7 +30,12 @@ ${c.output ?? ""}`.toLowerCase();
   "model-not-allowed": (c, cfg) => notInAllowList(c.model, cfg?.allowed),
   "tool-not-allowed": (c, cfg) => notInAllowList(c.tool, cfg?.allowed),
   "pii-present": (c) => c.piiPresent === true,
-  "rate-limit-exceeded": (c, cfg) => typeof c.callCount === "number" && c.callCount > Number(cfg?.max ?? 0)
+  "rate-limit-exceeded": (c, cfg) => typeof c.callCount === "number" && c.callCount > Number(cfg?.max ?? 0),
+  // Trust guidance (MetaMynd Trust Index / HCS-28). Fires when the counterparty's trust score is
+  // below a soft REVIEW line — intended to author an ESCALATE (route to a human), NOT a hard block.
+  // The score is server-derived (signed-last) so the agent's itinerary can't fake it; when no score
+  // is present (e.g. no counterparty resolved) the atom simply does not fire — no guidance.
+  "hol-trust-below-review": (c, cfg) => typeof c.holTrustScore === "number" && c.holTrustScore < Number(cfg?.reviewBelow ?? 60)
 };
 function notInAllowList(value, allowList) {
   const v = value != null ? String(value).toLowerCase().trim() : "";
@@ -39,9 +47,16 @@ function notInAllowList(value, allowList) {
 var ATOM_SPECS = [
   {
     predicate: "amount-over",
-    label: "Amount over limit",
-    description: "Fires when the action amount exceeds a configured limit.",
-    config: [{ key: "limit", type: "number", required: true, description: "Maximum allowed amount" }],
+    label: "Per-transaction amount over limit",
+    description: "Fires when a single action amount exceeds a configured limit (per-transaction cap).",
+    config: [{ key: "limit", type: "number", required: true, description: "Maximum allowed amount for one transaction" }],
+    requiredContext: ["amount"]
+  },
+  {
+    predicate: "cumulative-over",
+    label: "Total budget over limit",
+    description: "Fires when cumulative spend (already-spent + this transaction) exceeds a configured total budget.",
+    config: [{ key: "limit", type: "number", required: true, description: "Maximum total budget across all transactions" }],
     requiredContext: ["amount"]
   },
   {
@@ -123,6 +138,13 @@ var ATOM_SPECS = [
     description: "Fires when the rolling call count exceeds a configured maximum.",
     config: [{ key: "max", type: "number", required: true, description: "Maximum allowed calls" }],
     requiredContext: ["callCount"]
+  },
+  {
+    predicate: "hol-trust-below-review",
+    label: "Counterparty trust below review line",
+    description: "Routes to human review when the counterparty's MetaMynd Trust Index (HCS-28) score is below a soft review line. Guidance, not a hard block \u2014 author it with an ESCALATE decision. The score is resolved server-side; no counterparty score \u2192 the atom does not fire.",
+    config: [{ key: "reviewBelow", type: "number", required: true, description: "Trust score (0\u2013100) below which a human is asked to decide" }],
+    requiredContext: ["holTrustScore"]
   }
 ];
 var CATALOGUED_ATOMS = ATOM_SPECS.filter((s) => !!ATOM_REGISTRY[s.predicate]);