@metamynd/agentsafe-guard 0.2.0 → 0.3.0

package/policy-core.mjs

@@ -31,6 +31,25 @@ ${c.output ?? ""}`.toLowerCase();
   "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),
+  // --- Evidence-quality atoms (SAFR §24). Unlike the allow-list atoms, these fire on ABSENCE:
+  //     a REQUIRE semantic — "the action must be backed by this evidence; if it isn't, fire"
+  //     (author with escalate/block). Opt-in: they only run when a rule keys them. ---
+  // Fires when any REQUIRED evidence type is not among the attested `evidenceTypes` (missing
+  // evidence — including none supplied at all → all required missing → fires).
+  "evidence-requirement": (c, cfg) => {
+    const required = (cfg?.required ?? []).map((t) => String(t).toLowerCase().trim()).filter(Boolean);
+    if (required.length === 0) return false;
+    const have = new Set((Array.isArray(c.evidenceTypes) ? c.evidenceTypes : []).map((t) => String(t).toLowerCase().trim()));
+    return required.some((r) => !have.has(r));
+  },
+  // Fires when a required minimum confidence (min > 0) is not met — the attested confidence is
+  // below it, or absent (a required confidence that was never supplied fails the bar). A min of
+  // 0 / unset is no requirement and never fires.
+  "evidence-confidence-below": (c, cfg) => {
+    const min = Number(cfg?.min ?? 0);
+    if (!(min > 0)) return false;
+    return typeof c.evidenceConfidence !== "number" || c.evidenceConfidence < min;
+  },
   // 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
@@ -145,6 +164,20 @@ var ATOM_SPECS = [
     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"]
+  },
+  {
+    predicate: "evidence-requirement",
+    label: "Required evidence missing",
+    description: "Fires when the action is not backed by every REQUIRED evidence type the agent attests to in `evidenceTypes` (missing evidence \u2014 including none supplied). A REQUIRE control (SAFR \xA724): author it with ESCALATE or BLOCK so an under-evidenced action is stopped or reviewed.",
+    config: [{ key: "required", type: "string[]", required: true, description: "Evidence types that must all be present (e.g. kyc, source-doc, signature)" }],
+    requiredContext: ["evidenceTypes"]
+  },
+  {
+    predicate: "evidence-confidence-below",
+    label: "Evidence confidence below minimum",
+    description: "Fires when the attested evidence confidence is below a required minimum \u2014 or absent (SAFR \xA724). A min of 0 / unset is no requirement. Author with ESCALATE to route low-confidence actions to review.",
+    config: [{ key: "min", type: "number", required: true, description: "Minimum evidence confidence (0\u20131) required" }],
+    requiredContext: ["evidenceConfidence"]
   }
 ];
 var CATALOGUED_ATOMS = ATOM_SPECS.filter((s) => !!ATOM_REGISTRY[s.predicate]);
@@ -158,7 +191,7 @@ function requiredContextFor(predicates) {
 }
 
 // src/policy-core/standards-rules.ts
-var PRECEDENCE = { allow: 0, escalate: 1, block: 2 };
+var PRECEDENCE = { allow: 0, observe: 1, escalate: 2, block: 3, suspend: 4, quarantine: 5 };
 function atomFires(atom, ctx) {
   const pred = ATOM_REGISTRY[atom.predicate];
   if (!pred) return false;
@@ -244,8 +277,8 @@ function validateMolecules(molecules) {
     if (!["all", "any", "none"].includes(m.combinator)) {
       issues.push({ moleculeId: m.id, message: `invalid combinator '${m.combinator}' (all|any|none)` });
     }
-    if (!["block", "escalate"].includes(m.decision)) {
-      issues.push({ moleculeId: m.id, message: `invalid decision '${m.decision}' (block|escalate)` });
+    if (!["observe", "block", "escalate", "suspend", "quarantine"].includes(m.decision)) {
+      issues.push({ moleculeId: m.id, message: `invalid decision '${m.decision}' (observe|block|escalate|suspend|quarantine)` });
     }
     if (!m.reasonCode) issues.push({ moleculeId: m.id, message: "molecule is missing a reasonCode" });
     if (!m.atoms || m.atoms.length === 0) {
@@ -359,7 +392,7 @@ function sumEventField(events, type, field) {
 }
 
 // src/policy-core/evaluate.ts
-var PRECEDENCE2 = { allow: 0, escalate: 1, block: 2 };
+var PRECEDENCE2 = { allow: 0, observe: 1, escalate: 2, block: 3, suspend: 4, quarantine: 5 };
 function evaluate(input) {
   let decision = "allow";
   let reasonCode = "AUTHORIZED";
@@ -389,20 +422,66 @@ function buildAuthMessage(f) {
 function applySignedLast(unsigned, signed) {
   return { ...unsigned ?? {}, ...signed };
 }
+
+// src/policy-core/operating-mode.ts
+var MODE_RANK = {
+  read_only: 0,
+  restricted: 1,
+  supervised: 2,
+  autonomous: 3
+};
+var MODES_BY_RANK = ["read_only", "restricted", "supervised", "autonomous"];
+function isOperatingMode(v) {
+  return typeof v === "string" && Object.prototype.hasOwnProperty.call(MODE_RANK, v);
+}
+function asOperatingMode(v) {
+  return isOperatingMode(v) ? v : "autonomous";
+}
+function moreRestrictive(a, b) {
+  return MODE_RANK[a] <= MODE_RANK[b] ? a : b;
+}
+var SUPERVISED_AMOUNT_CAP = 100;
+var RISK_RANK2 = { low: 0, medium: 1, high: 2, critical: 3 };
+function riskAtOrAboveHigh(riskLevel) {
+  const r = typeof riskLevel === "string" ? RISK_RANK2[riskLevel.toLowerCase()] : void 0;
+  return r !== void 0 && r >= RISK_RANK2.high;
+}
+function operatingModeGate(mode, ctx) {
+  const m = asOperatingMode(mode);
+  const valueBearing = (ctx.amount ?? 0) > 0;
+  if (!valueBearing || m === "autonomous") return { decision: "allow", reasonCode: null };
+  switch (m) {
+    case "read_only":
+      return { decision: "block", reasonCode: "MODE_READ_ONLY" };
+    case "restricted":
+      return { decision: "escalate", reasonCode: "MODE_RESTRICTED_REVIEW" };
+    case "supervised":
+      return riskAtOrAboveHigh(ctx.riskLevel) || (ctx.amount ?? 0) >= SUPERVISED_AMOUNT_CAP ? { decision: "escalate", reasonCode: "MODE_SUPERVISED_REVIEW" } : { decision: "allow", reasonCode: null };
+    default:
+      return { decision: "allow", reasonCode: null };
+  }
+}
 export {
   ATOM_REGISTRY,
   ATOM_SPECS,
   CATALOGUED_ATOMS,
+  MODES_BY_RANK,
+  MODE_RANK,
+  SUPERVISED_AMOUNT_CAP,
   applyCapture,
   applyHold,
   applySignedLast,
+  asOperatingMode,
   buildAuthMessage,
   canAuthorize,
   evaluate,
   evaluateBoundStandards,
   evaluateMandate,
   evaluateStandardRules,
+  isOperatingMode,
   moleculeFires,
+  moreRestrictive,
+  operatingModeGate,
   releaseHold,
   remainingBudget,
   requiredContextFor,

package/x402.mjs

@@ -1,43 +1,43 @@
-// GENERATED from backend/src/features/magp/x402-binding.ts — do not edit. Regenerate: npm run build:guard-core
-
-// src/features/magp/x402-binding.ts
-function toMinorUnits(amount, decimals) {
-  if (!Number.isFinite(amount) || amount < 0) throw new Error("amount must be a non-negative number");
-  const factor = 10 ** decimals;
-  return String(Math.round(amount * factor));
-}
-function buildPaymentRequirements(input) {
-  if (!input.authorizationId) throw new Error("buildPaymentRequirements requires an authorizationId");
-  const decimals = input.decimals ?? 6;
-  return {
-    x402Version: 1,
-    accepts: [
-      {
-        scheme: "exact",
-        network: input.network ?? "hedera-testnet",
-        maxAmountRequired: toMinorUnits(input.amount, decimals),
-        payTo: input.payTo,
-        asset: input.asset,
-        resource: input.resource,
-        extra: { magpAuthorizationId: input.authorizationId, magpAgentDid: input.agentDid }
-      }
-    ]
-  };
-}
-function checkSettlementBinding(requirements, claim) {
-  const accept = requirements?.accepts?.[0];
-  if (!accept?.extra?.magpAuthorizationId) return { ok: false, reasonCode: "MISSING_BINDING" };
-  if (accept.extra.magpAuthorizationId !== claim.authorizationId) {
-    return { ok: false, reasonCode: "AUTHORIZATION_MISMATCH" };
-  }
-  const authorizedMinor = Number(accept.maxAmountRequired);
-  const paidMinor = Number(claim.paidAmountMinor);
-  if (!Number.isFinite(paidMinor) || paidMinor < 0) return { ok: false, reasonCode: "AMOUNT_INVALID" };
-  if (paidMinor > authorizedMinor) return { ok: false, reasonCode: "AMOUNT_MISMATCH" };
-  return { ok: true, reasonCode: "BINDING_OK" };
-}
-export {
-  buildPaymentRequirements,
-  checkSettlementBinding,
-  toMinorUnits
-};
+// GENERATED from backend/src/features/magp/x402-binding.ts — do not edit. Regenerate: npm run build:guard-core
+
+// src/features/magp/x402-binding.ts
+function toMinorUnits(amount, decimals) {
+  if (!Number.isFinite(amount) || amount < 0) throw new Error("amount must be a non-negative number");
+  const factor = 10 ** decimals;
+  return String(Math.round(amount * factor));
+}
+function buildPaymentRequirements(input) {
+  if (!input.authorizationId) throw new Error("buildPaymentRequirements requires an authorizationId");
+  const decimals = input.decimals ?? 6;
+  return {
+    x402Version: 1,
+    accepts: [
+      {
+        scheme: "exact",
+        network: input.network ?? "hedera-testnet",
+        maxAmountRequired: toMinorUnits(input.amount, decimals),
+        payTo: input.payTo,
+        asset: input.asset,
+        resource: input.resource,
+        extra: { magpAuthorizationId: input.authorizationId, magpAgentDid: input.agentDid }
+      }
+    ]
+  };
+}
+function checkSettlementBinding(requirements, claim) {
+  const accept = requirements?.accepts?.[0];
+  if (!accept?.extra?.magpAuthorizationId) return { ok: false, reasonCode: "MISSING_BINDING" };
+  if (accept.extra.magpAuthorizationId !== claim.authorizationId) {
+    return { ok: false, reasonCode: "AUTHORIZATION_MISMATCH" };
+  }
+  const authorizedMinor = Number(accept.maxAmountRequired);
+  const paidMinor = Number(claim.paidAmountMinor);
+  if (!Number.isFinite(paidMinor) || paidMinor < 0) return { ok: false, reasonCode: "AMOUNT_INVALID" };
+  if (paidMinor > authorizedMinor) return { ok: false, reasonCode: "AMOUNT_MISMATCH" };
+  return { ok: true, reasonCode: "BINDING_OK" };
+}
+export {
+  buildPaymentRequirements,
+  checkSettlementBinding,
+  toMinorUnits
+};