@metamynd/agentsafe-guard 0.12.0 → 0.12.4

package/agentsafe-guard.mjs

@@ -10,6 +10,7 @@
 // The agent's private key is a Hedera Ed25519 DER key (the AGENT_KEY the seed prints).
 import crypto from 'node:crypto';
 import { readFileSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
 import { evaluate, buildAuthMessage, applySignedLast, operatingModeGate } from './policy-core.mjs';
 import { envelopeHashFor } from './governance-envelope.mjs';
 import { verifyDidSignature } from './magp-did.mjs';
@@ -84,6 +85,38 @@ export function executionAdapterFromEnv(env = (typeof process !== 'undefined' ?
  *   agentDid the agent's did:hedera
  *   agentKey the agent's Ed25519 private key (Hedera DER hex, held only by the agent)
  */
+/**
+ * Read + parse an agent config file, failing with the NEXT STEP rather than a bare `ENOENT`.
+ * `agent.metamynd.json` holds the agent's identity (and, for a managed key, its secret), so it is
+ * deliberately gitignored — which means a fresh clone of any agent project can never contain it.
+ * A raw "no such file or directory" left a first-time user with no way forward (beta regression
+ * 2026-09-20, BR-004); the message below names the three ways to get the file.
+ */
+function readConfigFile(path, who) {
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') {
+      throw new Error([
+        `${who}: no agent config at "${resolvePath(path)}".`,
+        `  agent.metamynd.json holds the agent's identity and key, so it is gitignored - a fresh clone never has it.`,
+        `  To get one:`,
+        `    1. New agent:      npx create-metamynd-agent      (creates the agent and writes this file)`,
+        `    2. Existing agent: dashboard -> Agents -> your agent -> download its configuration, save it as ${path}`,
+        `    3. Kept elsewhere: pass its real path, e.g. createGuardFromConfig('/path/to/agent.metamynd.json')`,
+        `  Then re-run. Step-by-step: https://metamynd.ai/developers/quickstart`,
+      ].join('\n'));
+    }
+    throw new Error(`${who}: cannot read agent config "${path}": ${e && e.message}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new Error(`${who}: "${path}" is not valid JSON (${e.message}). Re-download the configuration rather than editing it by hand.`);
+  }
+}
+
 /**
  * Async loader — build a guard from the portable config the one-call `POST /onboarding/agent`
  * endpoint returns: a URL, a file path, or the config object itself. Overrides win over the config.
@@ -100,7 +133,7 @@ export function executionAdapterFromEnv(env = (typeof process !== 'undefined' ?
 export async function createGuardFromConfig(source, overrides = {}) {
   let cfg = source;
   if (typeof source === 'string') {
-    cfg = /^https?:\/\//.test(source) ? await (await fetch(source)).json() : JSON.parse(readFileSync(source, 'utf8'));
+    cfg = /^https?:\/\//.test(source) ? await (await fetch(source)).json() : readConfigFile(source, 'createGuardFromConfig');
   }
   if (cfg && cfg.data && !cfg.agentDid) cfg = cfg.data; // unwrap a { success, data } API response
   const { passphrase, ...rest } = overrides;
@@ -119,8 +152,7 @@ export function createGuard(opts = {}) {
   // addition to explicit { api, agentDid, agentKey }. Explicit fields win over the config.
   let cfg = opts.config ?? null;
   if (!cfg && opts.configPath) {
-    try { cfg = JSON.parse(readFileSync(opts.configPath, 'utf8')); }
-    catch (e) { throw new Error(`createGuard: cannot read configPath "${opts.configPath}": ${e.message}`); }
+    cfg = readConfigFile(opts.configPath, 'createGuard');
   }
   if (cfg && cfg.data && !cfg.agentDid) cfg = cfg.data; // unwrap a { success, data } API response
   const api = opts.api ?? cfg?.apiBase ?? cfg?.api;
@@ -297,7 +329,7 @@ export function createGuard(opts = {}) {
    * @param {Array<{standardKey:string,document:object}>} [p.standards] enforced Standards bound to the agent
    * @param {Array<{standardKey:string,document:object}>} [p.sops]      active SOPs assigned to the agent
    * @param {object} [p.mandate]  the ODRL mandate document (omit to skip the mandate layer)
-   * @param {{action:string,amount?:number,merchant?:string,context?:object,cumulativeSpend?:number,now?:string}} p.request
+   * @param {{action:string,amount?:number,currency?:string,merchant?:string,resource?:string,context?:object,cumulativeSpend?:number,now?:string}} p.request
    * @returns {{decision:'allow'|'block'|'escalate',reasonCode:string|null,authorizationId:null,remaining:null,proofRef:null}}
    */
   function evaluateLocally({ contained = null, operatingMode = null, standards = [], sops = [], mandate, request }) {
@@ -310,7 +342,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, currency = 'USD', merchant = '', context = {}, cumulativeSpend = amount, now } = request;
+    const { action, amount = 0, currency = 'USD', merchant = '', resource = null, 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
@@ -326,7 +358,11 @@ export function createGuard(opts = {}) {
       standards,
       sops,
       mandate,
-      context: applySignedLast(context, { action, agentDid, amount }),
+      // currency/merchant/resource are signed fields too, same as action/agentDid/amount —
+      // omitting them here means a currency-scoped amount-over/cumulative-over Standards/SOP
+      // atom always sees currency as absent and fires closed. Mirrors mandate.service.ts's
+      // ruleCtx (PR #588) and the same fix in agentsafe-mcp-guard.mjs's verdictFromBundle.
+      context: applySignedLast(context, { action, agentDid, amount, currency, merchant, resource }),
       mandateRequest: mandate
         ? {
             target: action,
@@ -341,6 +377,9 @@ export function createGuard(opts = {}) {
               // 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,
+              // Unprefixed `resource` (not `mm:resource`) to match the constraint's own
+              // leftOperand (ResourceService.scopeConstraint()) — mirrors mandate.service.ts.
+              resource,
             }),
           }
         : undefined,
@@ -372,14 +411,29 @@ export function createGuard(opts = {}) {
     return b;
   }
 
-  /** Map a fetched bundle into the shape evaluateLocally expects, for one action. */
+  /**
+   * Map a fetched bundle into the shape evaluateLocally expects, for one action.
+   *
+   * `mandateFound` distinguishes "no mandate matches THIS action" from "omit mandate to
+   * skip the layer" (evaluateLocally's own documented, intentional behavior for a caller
+   * that never resolves one at all, e.g. guardToolLocal's caller-supplied bundle) — found
+   * live: this used to fall back to `mandates[0]` (an ARBITRARY, possibly unrelated
+   * mandate for a completely different action) rather than correctly reporting no
+   * authority for this one, and `authorizeLocal` never distinguished either case from a
+   * genuinely-mandate-less bundle, so an ungranted action with no Standard/SOP rule
+   * happening to also catch it was silently ALLOWED instead of NO_PERMISSION_FOR_ACTION.
+   */
   function _bundleFor(b, action) {
+    const mandates = b.mandates ?? [];
+    const match = mandates.find((m) => m.action === action);
     return {
       contained: b.contained ?? null,
       operatingMode: b.operatingMode ?? null,
       standards: (b.standards ?? []).map((s) => ({ standardKey: s.id ?? s.standardKey ?? 'standard', document: s.document })).filter((s) => s.document),
       sops: (b.sops ?? []).map((s) => ({ standardKey: s.id ?? s.sopId ?? 'sop', document: s.document })).filter((s) => s.document),
-      mandate: ((b.mandates ?? []).find((m) => m.action === action) ?? (b.mandates ?? [])[0])?.document,
+      mandate: match?.document,
+      mandateFound: !!match,
+      anyMandates: mandates.length > 0,
     };
   }
 
@@ -470,7 +524,26 @@ export function createGuard(opts = {}) {
       const sig = b?.proof?.signature;
       if (!anchor?.sigDigest || !sig || _sha256(sig) !== anchor.sigDigest) return authorize(input);
     }
-    const local = evaluateLocally({ ..._bundleFor(b, action), request: input });
+    const { mandateFound, anyMandates, ...bundleForAction } = _bundleFor(b, action);
+    // No mandate covers this action at all — refuse outright rather than let evaluateLocally
+    // silently allow (its documented "omit mandate to skip the layer" behavior is for a
+    // caller that never intended a mandate check, not for one that looked and found none).
+    // Standards/SOP containment still applies first — a suspended/quarantined agent is
+    // refused for THAT reason, not misreported as merely lacking this one action.
+    if (!mandateFound) {
+      const contained = bundleForAction.contained;
+      if (contained && contained.status) {
+        const decision = contained.status === 'quarantined' ? 'quarantine' : 'suspend';
+        const reasonCode = contained.status === 'quarantined' ? 'AGENT_QUARANTINED' : 'AGENT_SUSPENDED';
+        const local = { decision, reasonCode, authorizationId: null, remaining: null, proofRef: null };
+        reportLocalDecision(action, local.decision, local.reasonCode);
+        return local;
+      }
+      const local = { decision: 'block', reasonCode: anyMandates ? 'NO_PERMISSION_FOR_ACTION' : 'NO_MANDATE', authorizationId: null, remaining: null, proofRef: null };
+      reportLocalDecision(action, local.decision, local.reasonCode);
+      return local;
+    }
+    const local = evaluateLocally({ ...bundleForAction, request: input });
     // allow/observe both PERMIT; block/escalate/contain are decided locally with no network.
     const permits = local.decision === 'allow' || local.decision === 'observe';
     if (!permits) {

package/cli.mjs

@@ -19,7 +19,19 @@ if (cmd === 'demo') {
   // or when a control named by --require is not configured at all.
   const { verify } = await import('./verify.mjs');
   try {
+    // --context <file>: the request context of a request that satisfies every rule (see verify.mjs).
+    let context;
+    // flag() is null when absent and '' when given with no value (`--context` last, or an unset shell
+    // variable) — the latter must be an error, not a silent bare run.
+    if (flag('context') !== null) {
+      const path = flag('context');
+      if (!path) throw new Error('--context needs a file path');
+      try { context = JSON.parse((await import('node:fs')).readFileSync(path, 'utf8')); }
+      catch (e) { throw new Error(`cannot read --context ${path}: ${e.message}`); }
+      if (context === null || typeof context !== 'object' || Array.isArray(context)) throw new Error(`--context ${path} must contain a JSON object`);
+    }
     const result = await verify({
+      context,
       configPath: flag('config') ?? './agent.metamynd.json',
       require: (flag('require') ?? '').split(',').map((s) => s.trim()).filter(Boolean),
       json: process.argv.includes('--json'),
@@ -50,6 +62,9 @@ if (cmd === 'demo') {
       --config <path>     agent config (default ./agent.metamynd.json)
       --require <a,b>     fail when a control is NOT configured, e.g.
                           --require merchants,perTxn
+      --context <path>    JSON file: the request context of a request that
+                          satisfies every rule (rule inputs like consent or
+                          evidenceTypes), for policies that require inputs
       --json              machine-readable output
 
     A control the mandate does not set is reported, never passed: an empty

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-guard",
-  "version": "0.12.0",
+  "version": "0.12.4",
   "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",
@@ -26,7 +26,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node demo.mjs && node local-eval.smoke.mjs && node execution-adapter.smoke.mjs && node verify.smoke.mjs && node context-signature.smoke.mjs && node local-decision-report.smoke.mjs && node resource-constraint.smoke.mjs && node passphrase-key.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 && node local-decision-report.smoke.mjs && node resource-constraint.smoke.mjs && node passphrase-key.smoke.mjs && node missing-config.smoke.mjs",
     "demo": "node demo.mjs"
   },
   "engines": {

package/verify.mjs

@@ -41,7 +41,7 @@ const CONTROLS = {
     detail: 'the ceiling on any single action',
     configured: (c) => {
       const k = c.find((x) => x.leftOperand === 'mm:payAmount' && x.operator === 'lteq');
-      return k ? { configured: true, summary: `${k.rightOperand}${k.unit ? ' ' + k.unit : ''}`, limit: Number(k.rightOperand) } : { configured: false };
+      return k ? { configured: true, summary: `${k.rightOperand}${k.unit ? ' ' + k.unit : ''}`, limit: Number(k.rightOperand), unit: k.unit } : { configured: false };
     },
   },
   cumulative: {
@@ -49,7 +49,7 @@ const CONTROLS = {
     detail: 'the ceiling on total spend across actions',
     configured: (c) => {
       const k = c.find((x) => x.leftOperand === 'mm:cumulativeSpend' && x.operator === 'lteq');
-      return k ? { configured: true, summary: `${k.rightOperand}${k.unit ? ' ' + k.unit : ''}`, limit: Number(k.rightOperand) } : { configured: false };
+      return k ? { configured: true, summary: `${k.rightOperand}${k.unit ? ' ' + k.unit : ''}`, limit: Number(k.rightOperand), unit: k.unit } : { configured: false };
     },
   },
   merchants: {
@@ -92,7 +92,15 @@ function packsFor(bundle, action) {
 
 const permits = (v) => v.decision === 'allow' || v.decision === 'observe';
 
-export async function verify({ configPath = './agent.metamynd.json', require: required = [], json = false, log = console.log, env = process.env } = {}) {
+/**
+ * `context` is the request context of a request that satisfies every rule in the agent's policy
+ * (rule inputs such as `consent`, `evidenceTypes`, `jurisdiction`). The baseline and cap checks send
+ * it, because a policy that REQUIRES an input blocks a request without it — which would make the
+ * baseline report a healthy agent as broken, and let a cap "hold" for the wrong reason. Omit it for
+ * a policy with no input-dependent rules (the old behaviour, unchanged). The scope check never
+ * uses it: an ungranted action must be refused whatever the context says.
+ */
+export async function verify({ configPath = './agent.metamynd.json', require: required = [], json = false, log = console.log, env = process.env, context: baseContext = {} } = {}) {
   // AGENT_KEY / AGENT_DID / METAMYND_API from the environment win over the config file.
   // CI is the whole point of this command, and a CI story that requires committing the
   // agent's signing key to the repository is not one — so a key-less config plus a secret
@@ -116,6 +124,12 @@ export async function verify({ configPath = './agent.metamynd.json', require: re
   const found = {};
   for (const [key, spec] of Object.entries(CONTROLS)) found[key] = spec.configured(constraints);
 
+  // The probes must be denominated in the currency the mandate's caps are. `evaluateLocally` assumes USD when a
+  // request names none, and a cap in any other currency refuses a currency-less or mismatched request (fail-closed),
+  // so a GBP agent would fail its own baseline check and read as broken. Only a cap that names a unit sets one.
+  const unitOf = (control) => (control.unit ? { currency: control.unit } : {});
+  const baselineCurrency = unitOf(found.perTxn.configured ? found.perTxn : found.cumulative);
+
   const checks = [];
   const add = (control, status, assertion, verdict, note) =>
     checks.push({ control, status, assertion, decision: verdict?.decision ?? null, reasonCode: verdict?.reasonCode ?? null, note });
@@ -125,7 +139,7 @@ export async function verify({ configPath = './agent.metamynd.json', require: re
   {
     const amount = found.perTxn.configured ? Math.max(1, Math.floor(found.perTxn.limit / 2)) : 1;
     const merchant = found.merchants.list?.length ? found.merchants.list[0] : 'any-merchant';
-    const v = evaluate({ action, amount, merchant, context: { riskLevel: 'low' } });
+    const v = evaluate({ action, amount, ...baselineCurrency, merchant, context: { riskLevel: 'low', ...baseContext } });
     add('baseline', permits(v) ? PASS : FAIL, 'permits ordinary in-scope work', v,
       permits(v) ? null : 'the agent cannot perform the action it was issued for');
   }
@@ -141,7 +155,7 @@ export async function verify({ configPath = './agent.metamynd.json', require: re
   // 3–5. Only assert a limit the mandate actually sets. Asserting an absent control is how
   //      you end up believing in one.
   if (found.perTxn.configured) {
-    const v = evaluate({ action, amount: found.perTxn.limit + 1, merchant: found.merchants.list?.length ? found.merchants.list[0] : 'any-merchant', context: {} });
+    const v = evaluate({ action, amount: found.perTxn.limit + 1, ...unitOf(found.perTxn), merchant: found.merchants.list?.length ? found.merchants.list[0] : 'any-merchant', context: { ...baseContext } });
     add('perTxn', permits(v) ? FAIL : PASS, `refuses ${found.perTxn.limit + 1} against a cap of ${found.perTxn.limit}`, v,
       permits(v) ? 'the per-transaction cap did not hold' : null);
   } else {
@@ -150,8 +164,8 @@ export async function verify({ configPath = './agent.metamynd.json', require: re
 
   if (found.cumulative.configured) {
     const v = evaluate({
-      action, amount: 1, merchant: found.merchants.list?.length ? found.merchants.list[0] : 'any-merchant',
-      cumulativeSpend: found.cumulative.limit + 1, context: {},
+      action, amount: 1, ...unitOf(found.cumulative), merchant: found.merchants.list?.length ? found.merchants.list[0] : 'any-merchant',
+      cumulativeSpend: found.cumulative.limit + 1, context: { ...baseContext },
     });
     add('cumulative', permits(v) ? FAIL : PASS, `refuses spending past a total of ${found.cumulative.limit}`, v,
       permits(v) ? 'the cumulative cap did not hold' : null);
@@ -166,7 +180,7 @@ export async function verify({ configPath = './agent.metamynd.json', require: re
     // Deliberately UNDER any cap: a refusal at an amount that also trips a spend limit
     // proves nothing about merchants, which is exactly how this went unnoticed before.
     const amt = found.perTxn.configured ? Math.max(1, Math.floor(found.perTxn.limit / 2)) : 1;
-    const v = evaluate({ action, amount: amt, merchant: '__unapproved_supplier__', context: {} });
+    const v = evaluate({ action, amount: amt, ...baselineCurrency, merchant: '__unapproved_supplier__', context: { ...baseContext } });
     add('merchants', permits(v) ? FAIL : PASS, 'refuses an unlisted merchant, under the cap', v,
       permits(v) ? 'the merchant allow-list did not hold' : null);
   } else {