@metamynd/agentsafe-guard 0.1.2 → 0.2.0

package/README.md

@@ -43,6 +43,62 @@ const guard = await createGuardFromConfig('./agent.metamynd.json');   // no env
 The rest of this guide shows the manual path (seed → wire) and the advanced features
 (local eval, handshake, escalation, payments).
 
+### Enforcement mode: local-first (default) or remote
+
+Since v0.2.0 the guard decides **locally by default**. `guardTool` (and the mode-aware
+`guard.check(...)`) evaluate the rule layer against the agent's cached signed policy
+bundle using the **same `policy-core` bytes the gate runs** — so a **block or escalate
+is decided with no network** (instant, works offline). An **allowed value action**
+(`amount > 0`) is still sealed by the remote gate, because the cumulative-spend cap,
+nonce/replay + atomic cap, and anchored evidence **must** be server-side. If the bundle
+can't be fetched, the guard defers to the authoritative remote gate rather than
+blind-allowing; a value action it can neither evaluate nor seal **fails closed**.
+
+```js
+// default — local-first
+const guard = await createGuardFromConfig('./agent.metamynd.json');
+// opt out — every call hits the gate
+const remote = await createGuardFromConfig('./agent.metamynd.json', { mode: 'remote' });
+// pure offline (no remote seal; drops cumulative-cap + evidence — you accept the trade)
+const offline = await createGuardFromConfig('./agent.metamynd.json', { mode: 'local', sealValueActions: false });
+```
+
+`guard.authorize(...)` is always the explicit **remote** call (unchanged);
+`guard.authorizeLocal(...)` is the explicit local-first call; `guard.check(...)` follows
+the configured `mode`. All return `{ decision, reasonCode, authorizationId, … }`.
+
+### Trustless currency check (`verifyOnChain`)
+
+Local eval trusts a bundle fetched over TLS. With `{ verifyOnChain: true }` the guard
+additionally confirms — from a **public Hedera mirror node, with MetaMynd offline** —
+that its local bundle is the **latest one anchored on the agent's own topic**. On each
+recompile MetaMynd publishes `sha256(bundle signature)` to the topic; the guard reads
+the latest `policy-update` op and requires `sha256(bundle.proof.signature)` to match it.
+If it can't confirm (mismatch / not yet anchored / mirror down), it **defers to the
+authoritative remote gate** rather than evaluate a bundle it can't prove is current.
+Append-only Hedera consensus makes the latest op authoritative and a **rollback**
+(serving an older signed bundle) detectable; a monotonic sequence number defeats a mirror
+that hides recent updates.
+
+```js
+const guard = await createGuardFromConfig('./agent.metamynd.json', { verifyOnChain: true });
+await guard.policyAnchor(); // → { sigDigest, seq } read from Hedera (or null)
+```
+
+### Push invalidation (`watchPolicy`)
+
+By default a rule change is picked up within the bundle's `maxStaleness` (or on the
+next on-chain check). `guard.watchPolicy()` subscribes to a Server-Sent-Events stream
+(`GET /policy/events/:did`, zero-dep — plain `fetch`) so a change **invalidates the
+guard's cache in ~1s** and the next call re-fetches (and re-verifies) the new rules.
+It auto-reconnects; a dropped stream still leaves staleness + the on-chain check as the
+floor, so a missed push degrades latency, never safety.
+
+```js
+const stop = guard.watchPolicy((change) => console.log('rules changed', change));
+// … later: stop.close();
+```
+
 ### Bring your own key (BYOK)
 
 Provision the agent with your **own** public key so MetaMynd never sees the private key. The identity

package/agentsafe-guard.mjs

@@ -55,6 +55,32 @@ export function createGuard(opts = {}) {
     return crypto.sign(null, Buffer.from(message, 'utf8'), privateKey).toString('hex');
   }
 
+  // --- 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
+  //   gate (two-phase hold + cumulative cap + evidence). 'remote': every call hits the gate.
+  const mode = opts.mode ?? cfg?.mode ?? 'local';
+  const bundleUrl = opts.bundleUrl ?? cfg?.bundleUrl ?? `${base}/policy/bundle/${encodeURIComponent(agentDid)}`;
+  const sealValueActions = opts.sealValueActions !== false; // default true
+  // Build B — trustless currency check. When on, the guard trusts its local bundle ONLY if that
+  // bundle is the LATEST one anchored on the agent's Hedera topic (read from a public mirror);
+  // otherwise it defers to the authoritative remote gate. Opt-in for now.
+  const verifyOnChain = opts.verifyOnChain ?? cfg?.verifyOnChain ?? false;
+  const _anchorTtlMs = opts.anchorTtlMs ?? 60_000;
+  let _bundle = null;
+  let _bundleAt = 0;
+  let _bundleMaxAgeMs = 10 * 60 * 1000; // overwritten by the bundle's maxStaleness
+  let _anchor = null;
+  let _anchorAt = 0;
+  let _highestSeq = 0; // monotonic: never accept a mirror response with fewer policy ops than seen
+
+  /** Parse an ISO-8601 duration like "PT10M" / "PT30S" / "PT1H" → ms (or null). */
+  function _durationMs(s) {
+    const m = /^PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?$/.exec(String(s ?? ''));
+    if (!m) return null;
+    return ((+m[1] || 0) * 3600 + (+m[2] || 0) * 60 + (+m[3] || 0)) * 1000 || null;
+  }
+
   /**
    * Build a signed authorize request (spec §7.2/§7.3) WITHOUT sending it — the object an
    * agent presents to a counterparty (e.g. an MCP) so the counterparty can re-verify the
@@ -145,6 +171,144 @@ export function createGuard(opts = {}) {
     });
   }
 
+  /** Fetch + cache the agent's signed policy bundle (refreshed per its maxStaleness). */
+  async function loadBundle(force = false) {
+    const now = Date.now();
+    if (!force && _bundle && now - _bundleAt < _bundleMaxAgeMs) return _bundle;
+    const res = await fetch(bundleUrl);
+    const body = await res.json().catch(() => null);
+    const b = body?.data ?? body;
+    if (!b || (!b.mandates && !b.sops && !b.standards)) throw new Error(`invalid policy bundle from ${bundleUrl}`);
+    _bundle = b;
+    _bundleAt = now;
+    _bundleMaxAgeMs = _durationMs(b.maxStaleness) ?? _bundleMaxAgeMs;
+    return b;
+  }
+
+  /** Map a fetched bundle into the shape evaluateLocally expects, for one action. */
+  function _bundleFor(b, action) {
+    return {
+      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,
+    };
+  }
+
+  const _sha256 = (s) => 'sha256:' + crypto.createHash('sha256').update(String(s)).digest('hex');
+
+  /**
+   * Read the CURRENT anchored policy for this agent from its OWN Hedera topic via a public
+   * mirror node — no MetaMynd call (Build B / spec §5.3.1). Returns { sigDigest, seq } of the
+   * latest `policy-update` op, or null. Cached for `_anchorTtlMs`; monotonic on `seq`.
+   */
+  async function _currentAnchor() {
+    const now = Date.now();
+    if (_anchor && now - _anchorAt < _anchorTtlMs) return _anchor;
+    const m = /^did:hedera:([^:]+):[^_]+_(.+)$/.exec(agentDid);
+    if (!m) return _anchor;
+    const network = m[1];
+    const topicId = m[2];
+    const mbase = network === 'mainnet' ? 'https://mainnet.mirrornode.hedera.com' : 'https://testnet.mirrornode.hedera.com';
+    try {
+      // Newest-first: the latest `policy-update` op for this DID is the current policy. Its topic
+      // sequence_number is the monotonic marker (globally increasing under Hedera consensus), so a
+      // rollback / a mirror hiding recent updates shows a LOWER seq and is rejected. (A very busy
+      // topic could bury the op past one page; a per-agent topic won't — pagination is a refinement.)
+      const body = await fetch(`${mbase}/api/v1/topics/${topicId}/messages?limit=100&order=desc`).then((r) => (r.ok ? r.json() : null));
+      const hit = (body?.messages ?? [])
+        .map((x) => { try { return { seq: Number(x.sequence_number), op: JSON.parse(Buffer.from(x.message, 'base64').toString('utf8')) }; } catch { return null; } })
+        .filter((e) => e && e.op?.op === 'policy-update' && e.op.did === agentDid)
+        .sort((a, b) => b.seq - a.seq)[0];
+      if (!hit) return _anchor;
+      const a = { sigDigest: hit.op.sigDigest ?? null, seq: hit.seq };
+      if (a.seq >= _highestSeq) { _anchor = a; _anchorAt = now; _highestSeq = a.seq; }
+    } catch { /* mirror unreachable — keep the last known anchor */ }
+    return _anchor;
+  }
+
+  /**
+   * LOCAL-FIRST decision (the default). Evaluates the rule layer against the cached
+   * bundle with the same policy-core the gate runs — so a block/escalate is decided
+   * with NO network. An allowed VALUE action (amount > 0) is then sealed by the remote
+   * gate (two-phase hold + cumulative-spend cap + anchored evidence — the parts that
+   * MUST be server-side); set `sealValueActions:false` for pure offline. If the bundle
+   * can't be loaded, defers to the authoritative remote gate rather than blind-allow.
+   */
+  async function authorizeLocal(input) {
+    const { action, amount = 0 } = input;
+    let b;
+    try {
+      b = await loadBundle();
+    } catch {
+      return authorize(input); // no local rules → authoritative remote gate
+    }
+    // Trustless currency check (Build B): trust the local bundle only if it is the LATEST one
+    // anchored on Hedera; otherwise defer to the authoritative remote gate (never evaluate against
+    // a bundle we can't prove is current — this defeats a stale/rolled-back or forged bundle).
+    if (verifyOnChain) {
+      const anchor = await _currentAnchor();
+      const sig = b?.proof?.signature;
+      if (!anchor?.sigDigest || !sig || _sha256(sig) !== anchor.sigDigest) return authorize(input);
+    }
+    const local = evaluateLocally({ ..._bundleFor(b, action), request: input });
+    if (local.decision !== 'allow') return local; // decided locally, no network
+    if (amount > 0 && sealValueActions) return authorize(input); // seal value action remotely
+    return local; // non-value allow — local is sufficient
+  }
+
+  /** Mode-aware decision used by guardTool: 'local' (default) or 'remote'. */
+  async function check(input) {
+    return mode === 'remote' ? authorize(input) : authorizeLocal(input);
+  }
+
+  /**
+   * Watch for policy changes over Server-Sent Events (Build C) — ZERO-dependency (plain fetch,
+   * no socket client). On a `policy:changed` push the guard invalidates its bundle + on-chain
+   * anchor cache, so the NEXT call re-fetches (and re-verifies) the new rules — reaching the edge
+   * in ~1s instead of within maxStaleness. Push is an optimization: a dropped stream still leaves
+   * staleness (A) + the on-chain check (B) as the floor. Auto-reconnects with a short backoff.
+   * Returns a handle with `.close()`. Optional `onChange(payload)` callback.
+   */
+  function watchPolicy(onChange) {
+    let stopped = false;
+    let controller = null;
+    (async () => {
+      while (!stopped) {
+        try {
+          controller = new AbortController();
+          const res = await fetch(`${base}/policy/events/${encodeURIComponent(agentDid)}`, {
+            headers: { Accept: 'text/event-stream' },
+            signal: controller.signal,
+          });
+          if (!res.ok || !res.body) throw new Error(`policy events ${res.status}`);
+          const reader = res.body.getReader();
+          const dec = new TextDecoder();
+          let buf = '';
+          while (!stopped) {
+            const { value, done } = await reader.read();
+            if (done) break;
+            buf += dec.decode(value, { stream: true });
+            let i;
+            while ((i = buf.indexOf('\n\n')) >= 0) {
+              const frame = buf.slice(0, i);
+              buf = buf.slice(i + 2);
+              if (!/^event:\s*policy:changed/m.test(frame)) continue; // ignore comments/heartbeats
+              _bundle = null; _bundleAt = 0; _anchor = null; _anchorAt = 0; // invalidate → next call re-fetches
+              if (onChange) {
+                const dline = frame.split('\n').find((l) => l.startsWith('data:'));
+                try { onChange(dline ? JSON.parse(dline.slice(5).trim()) : {}); } catch { /* ignore */ }
+              }
+            }
+          }
+        } catch {
+          /* stream dropped — reconnect */
+        }
+        if (!stopped) await new Promise((r) => setTimeout(r, 2000));
+      }
+    })();
+    return { close() { stopped = true; try { controller?.abort(); } catch { /* ignore */ } } };
+  }
+
   /**
    * Like guardTool, but evaluates LOCALLY against a policy bundle instead of calling
    * the gate — cooperative-mode, low-latency governance (spec §9.2). Fails CLOSED:
@@ -188,7 +352,7 @@ export function createGuard(opts = {}) {
    */
   function guardTool(action, handler, mapArgs = (a) => a) {
     return async (args) => {
-      const decision = await authorize({ action, ...mapArgs(args) });
+      const decision = await check({ action, ...mapArgs(args) });
       if (decision.decision !== 'allow') {
         const err = new Error(`AgentSafe ${decision.decision.toUpperCase()} "${action}": ${decision.reasonCode}`);
         err.name = 'GovernanceBlocked';
@@ -312,5 +476,5 @@ export function createGuard(opts = {}) {
     return sign(challenge);
   }
 
-  return { authorize, buildSignedRequest, capture, guardTool, evaluateLocally, guardToolLocal, handshake, preparePayment, escalationStatus, verifyKey, signChallenge, agentDid };
+  return { authorize, authorizeLocal, check, loadBundle, policyAnchor: _currentAnchor, watchPolicy, mode, verifyOnChain, buildSignedRequest, capture, guardTool, evaluateLocally, guardToolLocal, handshake, preparePayment, escalationStatus, verifyKey, signChallenge, agentDid };
 }

package/package.json

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