@metamynd/mmt-graph 0.2.0 → 0.3.2

package/mmt-graph.anchor-live-demo.mjs

@@ -67,15 +67,18 @@ function parseOperatorKey(raw) {
   }
 }
 
+const operatorPrivateKey = parseOperatorKey(operatorKey);
 const client = Client.forName(network);
-client.setOperator(AccountId.fromString(operatorId), parseOperatorKey(operatorKey));
+client.setOperator(AccountId.fromString(operatorId), operatorPrivateKey);
 
 async function ensureTopicId() {
   const fromEnv = process.env.MMT_GRAPH_TOPIC_ID;
   if (fromEnv) return fromEnv;
 
   console.log('No MMT_GRAPH_TOPIC_ID set — creating a fresh topic (set this env var to reuse it next time).');
-  const resp = await new TopicCreateTransaction().execute(client);
+  // Admin key IS set (the operator key) so this topic stays upgradeable later (e.g. an
+  // HSuite multisig validator key) — omitting it makes a topic permanently immutable.
+  const resp = await new TopicCreateTransaction().setAdminKey(operatorPrivateKey).execute(client);
   const topicId = (await resp.getReceipt(client)).topicId?.toString();
   if (!topicId) throw new Error('topic creation succeeded but returned no topicId');
   return topicId;

package/mmt-graph.project.mjs

@@ -20,6 +20,7 @@ export const MMT = 'https://schema.metamynd.ai/trust/v1#';
 const RDF_TYPE = namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type');
 const XSD_INTEGER = namedNode('http://www.w3.org/2001/XMLSchema#integer');
 const XSD_DATETIME = namedNode('http://www.w3.org/2001/XMLSchema#dateTime');
+const XSD_DECIMAL = namedNode('http://www.w3.org/2001/XMLSchema#decimal');
 
 const mmt = (local) => namedNode(MMT + local);
 
@@ -119,6 +120,13 @@ export function projectDecisionRecorded(ev) {
   const quads = [quad(decision, RDF_TYPE, mmt('AuthorizationDecision'))];
   if (ev.decisionDigest) quads.push(quad(decision, mmt('decisionDigest'), literal(ev.decisionDigest)));
   if (ev.agentDid) quads.push(quad(decision, mmt('decidedFor'), agentIri(ev.agentDid)));
+  // amount/currency/action/occurredAt: see this event's own header in mmt-graph.types.mjs —
+  // added for spend-anomaly.mjs's baseline-deviation query, which needs to ORDER BY
+  // occurredAt and aggregate over amount, hence the typed (not plain-string) literals.
+  if (ev.amount !== undefined) quads.push(quad(decision, mmt('amount'), literal(String(ev.amount), XSD_DECIMAL)));
+  if (ev.currency) quads.push(quad(decision, mmt('currency'), literal(ev.currency)));
+  if (ev.action) quads.push(quad(decision, mmt('action'), literal(ev.action)));
+  if (ev.occurredAt) quads.push(quad(decision, mmt('occurredAt'), literal(ev.occurredAt, XSD_DATETIME)));
   return quads;
 }
 

package/mmt-graph.spend-anomaly.mjs

@@ -0,0 +1,82 @@
+/**
+ * Spend-pattern anomaly detection (resilience review, item 4 — the one thing rate limits
+ * and circuit breakers genuinely don't cover). Both of those enforce a fixed threshold a
+ * human set ahead of time; neither notices "this specific agent's amount just jumped 10x
+ * its own normal pattern" unless someone happened to configure a cap at exactly that level.
+ * This queries the agent's OWN recorded history (mmt:AuthorizationDecision, populated by
+ * recordAuthorizationDecided — see mandate.service.ts) and flags a deviation from ITS
+ * baseline, not a pre-set number.
+ *
+ * Split the same way mandate-anchor-audit.ts and rate-window/circuit-breaker's logic/service
+ * files are: `recentAmounts` is the only I/O (a SPARQL SELECT against the engine, which is
+ * itself in-memory — no network, no DB, but still "ask the store" rather than pure
+ * computation); `isSpendAnomaly` is pure and independently testable with plain arrays.
+ */
+import { MMT } from './mmt-graph.project.mjs';
+
+/**
+ * The agent's most recent recorded decision amounts, newest first, optionally scoped to one
+ * action. Only decisions with BOTH an amount and an occurredAt are returned — one without
+ * the other cannot be ordered/aggregated meaningfully, and both are always set together by
+ * recordAuthorizationDecided, so an entry missing either predates that wiring or came from a
+ * different producer and is excluded rather than guessed at.
+ *
+ * @param engine {import('./mmt-graph.engine.mjs').MmtGraphEngine}
+ * @param agentDid {string}
+ * @param opts {{ action?: string, limit?: number }}
+ * @returns {number[]}
+ */
+export function recentAmounts(engine, agentDid, opts = {}) {
+  const limit = Number.isFinite(opts.limit) && opts.limit > 0 ? Math.floor(opts.limit) : 20;
+  const actionFilter = opts.action ? `FILTER(?action = ${JSON.stringify(opts.action)})` : '';
+  const rows = [
+    ...engine.query(`
+      PREFIX mmt: <${MMT}>
+      SELECT ?amount ?occurredAt WHERE {
+        ?d a mmt:AuthorizationDecision ;
+           mmt:decidedFor <${agentDid}> ;
+           mmt:amount ?amount ;
+           mmt:occurredAt ?occurredAt .
+        OPTIONAL { ?d mmt:action ?action }
+        ${actionFilter}
+      }
+      ORDER BY DESC(?occurredAt)
+      LIMIT ${limit}
+    `),
+  ];
+  return rows.map((r) => Number(r.get('amount').value));
+}
+
+/**
+ * Whether `currentAmount` deviates from `history`'s baseline enough to be a genuine anomaly
+ * rather than ordinary variance. Pure — no I/O, no clock, just arrays and numbers.
+ *
+ * - Too little history (`< minHistory`) never flags: a brand-new agent's first few real
+ *   transactions ARE its baseline, not a deviation from one that doesn't exist yet.
+ * - A near-zero stddev (a very regular spender — e.g. always exactly $50) falls back to a
+ *   flat multiple of the mean, because dividing by ~0 would make almost ANY amount read as
+ *   "many standard deviations away" and flag on trivial rounding noise.
+ * - Only a genuine INCREASE can flag. A smaller-than-usual amount is never "anomalous" in
+ *   the sense this exists to catch (an attacker extracting more than the agent normally
+ *   moves) — flagging a decrease would just be noise with no security value.
+ *
+ * @param history {number[]} — most recent amounts, current one NOT included
+ * @param currentAmount {number}
+ * @param opts {{ minHistory?: number, deviationMultiple?: number }}
+ */
+export function isSpendAnomaly(history, currentAmount, opts = {}) {
+  const minHistory = Number.isFinite(opts.minHistory) && opts.minHistory > 0 ? Math.floor(opts.minHistory) : 5;
+  const deviationMultiple = Number.isFinite(opts.deviationMultiple) && opts.deviationMultiple > 0 ? opts.deviationMultiple : 4;
+
+  if (history.length < minHistory) {
+    return { anomaly: false, reason: 'insufficient-history', mean: null, stddev: null, threshold: null };
+  }
+
+  const mean = history.reduce((a, b) => a + b, 0) / history.length;
+  const variance = history.reduce((a, b) => a + (b - mean) ** 2, 0) / history.length;
+  const stddev = Math.sqrt(variance);
+  const threshold = stddev > 0 ? mean + deviationMultiple * stddev : mean * deviationMultiple;
+
+  const anomaly = currentAmount > mean && currentAmount > threshold;
+  return { anomaly, reason: anomaly ? 'deviates-from-baseline' : null, mean, stddev, threshold };
+}

package/mmt-graph.types.mjs

@@ -60,6 +60,25 @@
  */
 /** @typedef {{ op: 'mandate-revoked', policyId: string }} MandateRevoked */
 
+/**
+ * Owner-initiated agent containment (distinct from a rule-fired suspend/quarantine,
+ * neither of which anchor to this graph today). `reason` is the free-text
+ * `AgentIdentity.containedReason` at the moment of decommission, capped the same way
+ * the DB column is.
+ *
+ * NOT YET WIRED to a projector or an adapter/backend call site (unlike
+ * MandateGranted/MandateRevoked, both of which have engine.mjs `#project()` cases —
+ * MandateRevoked's is just never invoked from a backend call site today). Applying
+ * AgentReinstated correctly needs a projector that clears just the prior
+ * containmentStatus/containmentReason quads for the agent — `apply()`'s only removal
+ * primitive today is `{removeSubject}`, which deletes the WHOLE agent node (its type,
+ * memberOf, mandates, cohorts…), not a single predicate. Add an
+ * `mmt-graph.engine.mjs` case (+ project.mjs projector) with a predicate-scoped
+ * removal before wiring an adapter call — until then this is vocabulary-only.
+ */
+/** @typedef {{ op: 'agent-decommissioned', agentDid: string, reason?: string }} AgentDecommissioned */
+/** @typedef {{ op: 'agent-reinstated', agentDid: string }} AgentReinstated */
+
 /**
  * Domain H (runtime activity/evidence) — Phase 5's first slice, proving the engine can
  * answer evidence-path.ts's "independently verifiable" question, not a full replacement
@@ -73,7 +92,17 @@
  * `mmt:decidedFor` since Domain H names no equivalent predicate (see
  * mmt-graph.accountability.mjs).
  */
-/** @typedef {{ op: 'decision-recorded', decisionId: string, decisionDigest?: string, agentDid?: string }} DecisionRecorded */
+/**
+ * `amount`/`currency`/`action`/`occurredAt`, added for the resilience-review's spend-
+ * pattern anomaly detector (mmt-graph.spend-anomaly.mjs): the graph already recorded that a
+ * decision happened, but not what it was FOR, so there was no history a baseline-deviation
+ * check could query. Deliberately only the fields spend-anomaly.mjs's SPARQL actually reads
+ * — not amountCharged/bookingRef/settlementTxHash, which belong to capture(), a different
+ * event this package does not yet model. Recorded only for a decision that PERMITTED
+ * (allow/observe) — a blocked/escalated attempt was never a real transaction and would
+ * corrupt the baseline it's meant to protect, not describe it.
+ */
+/** @typedef {{ op: 'decision-recorded', decisionId: string, decisionDigest?: string, agentDid?: string, amount?: number, currency?: string, action?: string, occurredAt?: string }} DecisionRecorded */
 /** @typedef {{ op: 'evidence-recorded', eventId: string, decisionDigest?: string, anchorStatus?: string }} EvidenceRecorded */
 /** @typedef {{ op: 'batch-anchored', batchId: string, memberEventIds: string[], anchorStatus?: string }} BatchAnchored */
 
@@ -161,10 +190,27 @@ export function mandateRevoked({ policyId }) {
   return ev;
 }
 
+/** @returns {AgentDecommissioned} */
+export function agentDecommissioned({ agentDid, reason }) {
+  const ev = { op: 'agent-decommissioned', agentDid, reason };
+  requireFields(ev, ['agentDid']);
+  return ev;
+}
+
+/** @returns {AgentReinstated} */
+export function agentReinstated({ agentDid }) {
+  const ev = { op: 'agent-reinstated', agentDid };
+  requireFields(ev, ['agentDid']);
+  return ev;
+}
+
 /** @returns {DecisionRecorded} */
-export function decisionRecorded({ decisionId, decisionDigest, agentDid }) {
-  const ev = { op: 'decision-recorded', decisionId, decisionDigest, agentDid };
+export function decisionRecorded({ decisionId, decisionDigest, agentDid, amount, currency, action, occurredAt }) {
+  const ev = { op: 'decision-recorded', decisionId, decisionDigest, agentDid, amount, currency, action, occurredAt };
   requireFields(ev, ['decisionId']);
+  if (amount !== undefined && (typeof amount !== 'number' || !Number.isFinite(amount))) {
+    throw new Error(`decision-recorded for ${decisionId}: amount must be a finite number`);
+  }
   return ev;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/mmt-graph",
-  "version": "0.2.0",
+  "version": "0.3.2",
   "type": "module",
   "description": "Reference trust-graph engine (Oxigraph/SPARQL + SHACL) + HCS-anchor contract: apply mutation events, validate the MMTO §3 authority-chain invariant, batch the changelog into a Merkle root ready to anchor, and verify a disclosed tenant graph with MetaMynd fully offline. Hosting-mode-agnostic — no MetaMynd backend, no Postgres, no MetaMynd credentials anywhere in the code path. See docs/design/metamynd-trust-ontology.md Appendix C.",
   "main": "mmt-graph.engine.mjs",
@@ -14,7 +14,8 @@
     "./contagion": "./mmt-graph.contagion.mjs",
     "./accountability": "./mmt-graph.accountability.mjs",
     "./blast-radius": "./mmt-graph.blast-radius.mjs",
-    "./auditor": "./mmt-graph.auditor.mjs"
+    "./auditor": "./mmt-graph.auditor.mjs",
+    "./spend-anomaly": "./mmt-graph.spend-anomaly.mjs"
   },
   "bin": {
     "mmt-graph-auditor": "mmt-graph.auditor-cli.mjs"
@@ -35,11 +36,12 @@
     "mmt-graph.auditor.mjs",
     "mmt-graph.auditor-cli.mjs",
     "mmt-graph.self-host-quickstart.mjs",
+    "mmt-graph.spend-anomaly.mjs",
     "README.md"
   ],
   "scripts": {
     "spike": "node mmt-graph.spike.mjs",
-    "test": "node mmt-graph.test.mjs && node mmt-graph.merkle.test.mjs && node mmt-graph.changelog.test.mjs && node mmt-graph.anchor.test.mjs && node mmt-graph.evidence-path.test.mjs && node mmt-graph.contagion.test.mjs && node mmt-graph.accountability.test.mjs && node mmt-graph.blast-radius.test.mjs && node mmt-graph.auditor.test.mjs",
+    "test": "node mmt-graph.test.mjs && node mmt-graph.merkle.test.mjs && node mmt-graph.changelog.test.mjs && node mmt-graph.anchor.test.mjs && node mmt-graph.evidence-path.test.mjs && node mmt-graph.contagion.test.mjs && node mmt-graph.accountability.test.mjs && node mmt-graph.blast-radius.test.mjs && node mmt-graph.auditor.test.mjs && node mmt-graph.spend-anomaly.test.mjs",
     "anchor-live-demo": "node mmt-graph.anchor-live-demo.mjs",
     "auditor": "node mmt-graph.auditor-cli.mjs",
     "self-host-quickstart": "node mmt-graph.self-host-quickstart.mjs"