@metamynd/agentsafe-guard 0.5.1 → 0.6.3

package/README.md

@@ -25,7 +25,7 @@ re-implement the gate:
 ([markdown](https://metamynd.ai/specs/magp-v1.0.md))
 
 It defines agent identity, the canonical signed message (§8.3), the sixteen-stage order of
-checks (§8.5), all 59 reason codes (Appendix A), delegation narrowing (§5.4), and evidence
+checks (§8.5), all 62 reason codes (Appendix A), delegation narrowing (§5.4), and evidence
 you can verify offline without MetaMynd (§13.4). If you are writing a client in a language
 other than JavaScript, read §8.3.3–8.3.5 first: key encoding, number stringification and
 signed-vs-sent field identity each surface only as `SIGNATURE_INVALID`.
@@ -78,6 +78,19 @@ you state *our agents must carry a merchant allow-list* and find out when one do
 `--json` for machine-readable output. Evaluation is local and pure: no holds are minted, no
 nonces spent, no budget consumed, and a run costs one GET.
 
+**0.6.0 — `amount-unknown`.** The same discipline applied to the amount itself: a spend cap
+is only as good as the number it's checked against, and a signed-transaction or nested x402
+payload can carry its amount somewhere a naive check never looks. `amount-unknown` is a
+deny-by-default atom for exactly that case — an action whose value the gate can't determine
+is blocked, not silently waved through an untested cap.
+
+**0.6.2 — `amount-unknown` closes negative amounts too.** A negative `amount` (e.g. `-5`)
+previously read as "a real, known number" and sailed straight past `amount-unknown` — and
+past a naive `amount-over` cap, since `-5 > 500` is never true. An attacker submitting a
+negative value could clear a spend cap for free, or erode a cumulative-spend tracker that
+sums signed amounts over time. `amount-unknown` now fires on any non-finite, non-numeric,
+**or negative** amount; a genuine `0` still passes.
+
 ```yaml
 # .github/workflows/governance.yml
 name: Governance
@@ -98,6 +111,36 @@ jobs:
 set `AGENT_KEY` in the environment — `AGENT_KEY`, `AGENT_DID` and `METAMYND_API` all
 override the file when present.
 
+### As a packaged Action
+
+Same check, packaged so you don't hand-roll the workflow above — and it writes a
+pass/fail table straight into the PR's checks summary instead of a log a reviewer has to
+open:
+
+```yaml
+# .github/workflows/governance.yml
+name: Governance
+on: [push, pull_request]
+
+jobs:
+  mandate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: Metamynd/agentsafe-guard/packages/agentsafe-guard@v0.6.2
+        with:
+          config: ./agent.metamynd.json
+          require: merchants,perTxn
+        env:
+          AGENT_KEY: ${{ secrets.AGENT_KEY }}
+```
+
+Pinned to a released tag, the same way you'd pin any third-party action — not `@main`,
+which moves under you every time this repository resyncs. Inputs: `config` (default
+`./agent.metamynd.json`), `require`, `version` (the `@metamynd/agentsafe-guard` npm range
+to run, default `latest`), `working-directory`. Output: `ok` (`"true"`/`"false"`), if a
+later step needs to branch on the result.
+
 ## Install
 
 ```bash

package/agentsafe-guard.mjs

@@ -226,7 +226,7 @@ export function createGuard(opts = {}) {
       const reasonCode = contained.status === 'quarantined' ? 'AGENT_QUARANTINED' : 'AGENT_SUSPENDED';
       return { decision, reasonCode, authorizationId: null, remaining: null, proofRef: null };
     }
-    const { action, amount = 0, merchant = '', context = {}, cumulativeSpend = amount, now } = request;
+    const { action, amount = 0, currency = 'USD', merchant = '', context = {}, cumulativeSpend = amount, now } = request;
     // Operating-mode autonomy ladder (Phase 2.5b): the trust-driven posture rides as a
     // SIBLING (like `contained`) and biases the edge verdict identically to the gate.
     // READ_ONLY denies a value-bearing action up-front; SUPERVISED/RESTRICTED only
@@ -251,6 +251,12 @@ export function createGuard(opts = {}) {
               'mm:payAmount': amount,
               'mm:cumulativeSpend': cumulativeSpend,
               'mm:merchant': merchant,
+              // A payAmount/cumulativeSpend constraint issued with a `unit` (currency) is
+              // only satisfied in that currency (see mandate-eval.ts's constraintSatisfied)
+              // — omitting this here would make EVERY unit-bearing cap fail regardless of
+              // amount, since undefined never equals a real unit. Defaults to 'USD' to match
+              // the same default this file already uses for authorize()/buildSignedRequest().
+              'mm:currency': currency,
             }),
           }
         : undefined,
@@ -417,7 +423,7 @@ export function createGuard(opts = {}) {
    *
    * @param {string} action
    * @param {(args:any, decision:any)=>any} handler
-   * @param {(args:any)=>{amount?:number,merchant?:string,context?:object}} mapArgs
+   * @param {(args:any)=>{amount?:number,currency?:string,merchant?:string,context?:object}} mapArgs
    * @param {object|((args:any)=>object|Promise<object>)} getBundle  { standards, sops, mandate } (or a resolver)
    */
   function guardToolLocal(action, handler, mapArgs = (a) => a, getBundle = {}, toolOpts = {}) {
@@ -425,9 +431,9 @@ export function createGuard(opts = {}) {
     return async (args) => {
       let decision;
       try {
-        const { amount, merchant, context } = mapArgs(args);
+        const { amount, currency, merchant, context } = mapArgs(args);
         const bundle = typeof getBundle === 'function' ? await getBundle(args) : getBundle;
-        decision = evaluateLocally({ ...bundle, request: { action, amount, merchant, context } });
+        decision = evaluateLocally({ ...bundle, request: { action, amount, currency, merchant, context } });
       } catch (err) {
         decision = { decision: 'block', reasonCode: 'LOCAL_EVAL_ERROR', error: String(err?.message ?? err) };
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-guard",
-  "version": "0.5.1",
+  "version": "0.6.3",
   "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",

package/policy-core.mjs

@@ -11,6 +11,24 @@ 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),
+  // Deny-by-default primitive for value-moving actions. Fires on ABSENCE (like the
+  // evidence atoms below, and unlike `amount-over`) OR on a NEGATIVE amount: true when
+  // the context carries no usable amount, or one that cannot be trusted for capping —
+  // the gate cannot tell how much value the call would move, so a spend cap authored
+  // next to it would silently never fire. `amount-over` only ever fires on `> limit`,
+  // so a negative amount clears every positive cap by construction, and on a system
+  // that tracks committed spend ADDITIVELY (reserved += amount), a negative claim can
+  // net-reduce what's already committed rather than add to it — the same "cap never
+  // fires" failure as a missing amount, reached from the other side of zero. Zero
+  // itself is NOT covered here: a genuine $0 action (a read, a no-op) is a valid,
+  // known amount, not an unknown one. Author this with BLOCK as the FIRST rule of a
+  // spend policy; the cap that follows then only ever judges a known, non-negative
+  // number. Opt-in: only a rule that keys it runs it, so actions that carry no amount
+  // by nature are unaffected. The public authorize endpoint's own schema already
+  // rejects a negative amount before it reaches this atom (defense in depth, not the
+  // only layer) — this is what closes the same gap for paths that schema doesn't
+  // cover: the local/harness evaluator and the platform's own MCP tool policies.
+  "amount-unknown": (c) => !(typeof c.amount === "number" && Number.isFinite(c.amount) && c.amount >= 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),
@@ -58,8 +76,9 @@ ${c.output ?? ""}`.toLowerCase();
 };
 function notInAllowList(value, allowList) {
   const v = value != null ? String(value).toLowerCase().trim() : "";
+  if (v === "") return false;
   const allowed = (Array.isArray(allowList) ? allowList : []).map((x) => String(x).toLowerCase().trim());
-  return v !== "" && allowed.length > 0 && !allowed.includes(v);
+  return !allowed.includes(v);
 }
 
 // src/policy-core/atom-catalog.ts
@@ -71,6 +90,13 @@ var ATOM_SPECS = [
     config: [{ key: "limit", type: "number", required: true, description: "Maximum allowed amount for one transaction" }],
     requiredContext: ["amount"]
   },
+  {
+    predicate: "amount-unknown",
+    label: "Amount not determinable",
+    description: "Fires when the action carries no usable amount, or a NEGATIVE one \u2014 the gate cannot trust either for capping. A deny-by-default control for value-moving actions: author it with BLOCK ahead of a spend cap, otherwise an amount that is missing, unparseable, or negative passes the cap untested (amount-over only ever fires above the limit, so a negative amount clears every positive cap). A genuine $0 amount does NOT fire this \u2014 only attach it to actions that must always carry a real, non-negative amount.",
+    config: [],
+    requiredContext: ["amount"]
+  },
   {
     predicate: "cumulative-over",
     label: "Total budget over limit",
@@ -191,7 +217,7 @@ function requiredContextFor(predicates) {
 }
 
 // src/policy-core/standards-rules.ts
-var PRECEDENCE = { allow: 0, observe: 1, escalate: 2, block: 3, suspend: 4, quarantine: 5 };
+var PRECEDENCE = { allow: 0, observe: 1, escalate: 2, block: 3, suspend: 4, quarantine: 5, decommission: 6 };
 function atomFires(atom, ctx) {
   const pred = ATOM_REGISTRY[atom.predicate];
   if (!pred) return false;
@@ -329,7 +355,9 @@ function constraintSatisfied(c, req) {
   const op = OPERATORS[c.operator];
   if (!op) return false;
   const left = Object.prototype.hasOwnProperty.call(req.values, c.leftOperand) ? req.values[c.leftOperand] : void 0;
-  return op(left, c.rightOperand);
+  if (!op(left, c.rightOperand)) return false;
+  if (c.unit && req.values["mm:currency"] !== c.unit) return false;
+  return true;
 }
 function targetOf(rule, mandate) {
   return rule.target ?? mandate.target;
@@ -399,7 +427,7 @@ function sumEventField(events, type, field) {
 }
 
 // src/policy-core/evaluate.ts
-var PRECEDENCE2 = { allow: 0, observe: 1, escalate: 2, block: 3, suspend: 4, quarantine: 5 };
+var PRECEDENCE2 = { allow: 0, observe: 1, escalate: 2, block: 3, suspend: 4, quarantine: 5, decommission: 6 };
 function evaluate(input) {
   let decision = "allow";
   let reasonCode = "AUTHORIZED";
@@ -421,8 +449,11 @@ function evaluate(input) {
 }
 
 // src/policy-core/canonical.ts
+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}`;
+  return [f.agentDid, f.action, f.amount, f.currency, f.merchant ?? "", f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
 }
 
 // src/policy-core/context.ts