@fidacy/mcp 0.1.17 → 0.1.19

package/README.md

@@ -73,6 +73,9 @@ Mental model: `assess_action` -> **engine** (signed verdict);
 | `request_payment` | core | Authorize a payment action. ALLOW + grant, or DENY + rule. |
 | `verify_mandate` | core | Read the mandate envelope + Fidacy public key. |
 | `get_audit_proof` | core | Hash-chained proof for a decision id. |
+| `anchor_artifact` | engine | Bitcoin-anchored integrity proof for any file (contract, invoice, prescription, claim, image, audio, video, conversation). Hashed locally; only the SHA-256 leaves. Returns a signed receipt. |
+| `check_artifact` | engine | Check whether a file (or hash) was anchored, and its Bitcoin checkpoint state. A mismatch is the tampering signal. |
+| `upgrade` | — | Start upgrading this local install to a real Fidacy account; preserves and migrates anonymous usage. |
 
 ### `assess_action`
 
@@ -145,6 +148,21 @@ repository stays private. Set `FIDACY_MODE=http` and implement three endpoints:
 
 No change to the MCP layer is needed.
 
+## Telemetry
+
+The install emits **anonymous, opt-out** usage telemetry so we can measure
+traction (installs, active agents, decision counts, deny-rate). It is
+best-effort and never on the decision critical path, so it can never block or
+slow a verdict.
+
+- It carries an anonymous install id and counters only. It **never** includes
+  payment content — no payee, amount, invoice, or mandate ever leaves your
+  machine. Payload-carrying types are rejected by a strict schema.
+- Turn it off completely with `FIDACY_DISABLE_TELEMETRY=1` (or `true`).
+
+Consistent with the product: you don't have to trust us, you can verify. The
+firewall runs fully with telemetry disabled.
+
 ## Dev
 
 ```bash

package/dist/assess.js

@@ -88,7 +88,7 @@ async function postOnce(fetchImpl, url, headers, payload, timeoutMs) {
       body: payload,
       signal: controller.signal
     });
-  } catch (err) {
+  } catch {
     const aborted = controller.signal.aborted;
     throw new AssessError({ type: aborted ? "timeout" : "network_error", status: 0 });
   } finally {

package/dist/core.js

@@ -347,6 +347,9 @@ var FileAuditStore = class {
     const digest = sha256(stableStringify({ decisionId: decision.decisionId, status: decision.status, request: decision.request, violatedRule: decision.violatedRule ?? null }));
     const hash = sha256(`${prevHash}|${digest}|${seq}|${ts}`);
     const record2 = { seq, decisionId: decision.decisionId, status: decision.status, subject: decision.subject, digest, prevHash, hash, ts };
+    if (typeof decision.request?.purpose === "string" && decision.request.purpose.trim()) {
+      record2.purpose = decision.request.purpose.slice(0, 500);
+    }
     if (decision.status === "ALLOW") {
       const req = decision.request;
       if (typeof req?.amount === "number" && Number.isFinite(req.amount))
@@ -439,7 +442,25 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.1.17" : "dev";
+var CLIENT_VERSION = true ? "0.1.19" : "dev";
+function bandOf(amount) {
+  if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
+  if (amount < 10) return "lt10";
+  if (amount < 100) return "10_99";
+  if (amount < 1e3) return "100_999";
+  if (amount < 1e4) return "1k_10k";
+  if (amount < 1e5) return "10k_100k";
+  return "gte100k";
+}
+function capRatioOf(amount, perTxMax) {
+  if (typeof amount !== "number" || typeof perTxMax !== "number") return void 0;
+  if (!Number.isFinite(amount) || !Number.isFinite(perTxMax) || perTxMax <= 0 || amount <= perTxMax) return void 0;
+  const r = amount / perTxMax;
+  if (r < 2) return "1_2x";
+  if (r < 5) return "2_5x";
+  if (r < 10) return "5_10x";
+  return "gt10x";
+}
 var currentShell = "mcp";
 function telemetryEnabled() {
   const v = (process.env.FIDACY_DISABLE_TELEMETRY ?? "").trim().toLowerCase();
@@ -469,9 +490,17 @@ function resultOf(status, violatedRule) {
   if (r.startsWith("non_positive_amount") || r.startsWith("invalid_")) return "deny_invalid";
   return "deny_scope";
 }
-function record(type, result) {
+function record(type, result, band, capRatio) {
   if (!telemetryEnabled()) return;
-  buffer.push({ type, ts: (/* @__PURE__ */ new Date()).toISOString(), client_version: CLIENT_VERSION, shell: currentShell, ...result ? { result } : {} });
+  buffer.push({
+    type,
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    client_version: CLIENT_VERSION,
+    shell: currentShell,
+    ...result ? { result } : {},
+    ...band ? { band } : {},
+    ...capRatio ? { cap_ratio: capRatio } : {}
+  });
   if (!flushTimer) {
     flushTimer = setTimeout(() => {
       void flush();
@@ -479,7 +508,7 @@ function record(type, result) {
     if (typeof flushTimer.unref === "function") flushTimer.unref();
   }
 }
-var recordDecision = (status, violatedRule) => record("decision", resultOf(status, violatedRule));
+var recordDecision = (status, violatedRule, amount, perTxMax) => record("decision", resultOf(status, violatedRule), bandOf(amount), capRatioOf(amount, perTxMax));
 async function flush() {
   if (flushTimer) {
     clearTimeout(flushTimer);
@@ -541,10 +570,11 @@ function makeCore() {
     if (!url || !key) throw new Error("FIDACY_MODE=http requires FIDACY_API_URL and FIDACY_API_KEY");
     return new HttpFidacyCore(url, key, process.env.FIDACY_PUBLIC_KEY_PEM ?? "");
   }
+  let activeMandate = buildMandate();
   const dev = new DevFidacyCore({
-    mandate: buildMandate(),
+    mandate: activeMandate,
     auditLogPath: auditLogPath(),
-    onDecision: (d) => recordDecision(d.status, d.violatedRule)
+    onDecision: (d) => recordDecision(d.status, d.violatedRule, d.request?.amount, activeMandate?.allow?.perTxMax)
   });
   const mtimeOf = () => statSync(configPath(), { throwIfNoEntry: false })?.mtimeMs ?? 0;
   let seenMtime = mtimeOf();
@@ -552,7 +582,8 @@ function makeCore() {
     const m = mtimeOf();
     if (m !== seenMtime) {
       seenMtime = m;
-      dev.setMandate(buildMandate());
+      activeMandate = buildMandate();
+      dev.setMandate(activeMandate);
     }
   };
   return {

package/dist/index.js

@@ -354,6 +354,9 @@ var FileAuditStore = class {
     const digest = sha256(stableStringify({ decisionId: decision.decisionId, status: decision.status, request: decision.request, violatedRule: decision.violatedRule ?? null }));
     const hash = sha256(`${prevHash}|${digest}|${seq}|${ts}`);
     const record2 = { seq, decisionId: decision.decisionId, status: decision.status, subject: decision.subject, digest, prevHash, hash, ts };
+    if (typeof decision.request?.purpose === "string" && decision.request.purpose.trim()) {
+      record2.purpose = decision.request.purpose.slice(0, 500);
+    }
     if (decision.status === "ALLOW") {
       const req = decision.request;
       if (typeof req?.amount === "number" && Number.isFinite(req.amount))
@@ -468,7 +471,25 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.1.17" : "dev";
+var CLIENT_VERSION = true ? "0.1.19" : "dev";
+function bandOf(amount) {
+  if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
+  if (amount < 10) return "lt10";
+  if (amount < 100) return "10_99";
+  if (amount < 1e3) return "100_999";
+  if (amount < 1e4) return "1k_10k";
+  if (amount < 1e5) return "10k_100k";
+  return "gte100k";
+}
+function capRatioOf(amount, perTxMax) {
+  if (typeof amount !== "number" || typeof perTxMax !== "number") return void 0;
+  if (!Number.isFinite(amount) || !Number.isFinite(perTxMax) || perTxMax <= 0 || amount <= perTxMax) return void 0;
+  const r = amount / perTxMax;
+  if (r < 2) return "1_2x";
+  if (r < 5) return "2_5x";
+  if (r < 10) return "5_10x";
+  return "gt10x";
+}
 var currentShell = "mcp";
 function telemetryEnabled() {
   const v = (process.env.FIDACY_DISABLE_TELEMETRY ?? "").trim().toLowerCase();
@@ -498,9 +519,17 @@ function resultOf(status, violatedRule) {
   if (r.startsWith("non_positive_amount") || r.startsWith("invalid_")) return "deny_invalid";
   return "deny_scope";
 }
-function record(type, result) {
+function record(type, result, band, capRatio) {
   if (!telemetryEnabled()) return;
-  buffer.push({ type, ts: (/* @__PURE__ */ new Date()).toISOString(), client_version: CLIENT_VERSION, shell: currentShell, ...result ? { result } : {} });
+  buffer.push({
+    type,
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    client_version: CLIENT_VERSION,
+    shell: currentShell,
+    ...result ? { result } : {},
+    ...band ? { band } : {},
+    ...capRatio ? { cap_ratio: capRatio } : {}
+  });
   if (!flushTimer) {
     flushTimer = setTimeout(() => {
       void flush();
@@ -510,7 +539,7 @@ function record(type, result) {
 }
 var recordInstall = () => record("install");
 var recordAgentActive = () => record("agent_active");
-var recordDecision = (status, violatedRule) => record("decision", resultOf(status, violatedRule));
+var recordDecision = (status, violatedRule, amount, perTxMax) => record("decision", resultOf(status, violatedRule), bandOf(amount), capRatioOf(amount, perTxMax));
 var recordUpgradeIntent = () => record("upgrade_intent");
 async function flush() {
   if (flushTimer) {
@@ -573,10 +602,11 @@ function makeCore() {
     if (!url || !key) throw new Error("FIDACY_MODE=http requires FIDACY_API_URL and FIDACY_API_KEY");
     return new HttpFidacyCore(url, key, process.env.FIDACY_PUBLIC_KEY_PEM ?? "");
   }
+  let activeMandate = buildMandate();
   const dev = new DevFidacyCore({
-    mandate: buildMandate(),
+    mandate: activeMandate,
     auditLogPath: auditLogPath(),
-    onDecision: (d) => recordDecision(d.status, d.violatedRule)
+    onDecision: (d) => recordDecision(d.status, d.violatedRule, d.request?.amount, activeMandate?.allow?.perTxMax)
   });
   const mtimeOf = () => statSync(configPath(), { throwIfNoEntry: false })?.mtimeMs ?? 0;
   let seenMtime = mtimeOf();
@@ -584,7 +614,8 @@ function makeCore() {
     const m = mtimeOf();
     if (m !== seenMtime) {
       seenMtime = m;
-      dev.setMandate(buildMandate());
+      activeMandate = buildMandate();
+      dev.setMandate(activeMandate);
     }
   };
   return {
@@ -691,7 +722,7 @@ async function postOnce(fetchImpl, url, headers, payload, timeoutMs) {
       body: payload,
       signal: controller.signal
     });
-  } catch (err) {
+  } catch {
     const aborted = controller.signal.aborted;
     throw new AssessError({ type: aborted ? "timeout" : "network_error", status: 0 });
   } finally {
@@ -783,7 +814,7 @@ async function findArtifacts(sha2562, cfg) {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.1.17" : "dev";
+var CLIENT_VERSION2 = true ? "0.1.19" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -883,7 +914,7 @@ function weekOneBootNudge(upgradeToolName) {
 var state = ensureState();
 var core = makeCore();
 var subject = process.env.FIDACY_SUBJECT ?? "agent:demo";
-var SERVER_VERSION = true ? "0.1.17" : "dev";
+var SERVER_VERSION = true ? "0.1.19" : "dev";
 var server = new McpServer({ name: "fidacy", version: SERVER_VERSION });
 server.registerTool(
   "request_payment",
@@ -894,7 +925,9 @@ server.registerTool(
       payee: z.string().describe("Payee identifier"),
       amount: z.number().positive().describe("Amount in the mandate currency"),
       currency: z.string().length(3).describe("ISO 4217 currency code"),
-      purpose: z.string().describe("Human-readable purpose"),
+      purpose: z.string().describe(
+        "Your stated reason for this payment, in your own words. It is persisted readably on the tamper-evident audit record (ALLOW and DENY alike) and becomes part of the after-the-fact proof, so write the real reason."
+      ),
       category: z.string().describe("Purpose category (must be allowed by the mandate)"),
       idempotencyKey: z.string().describe("Caller-supplied idempotency key"),
       invoiceRef: z.string().describe(

package/dist/lib.js

@@ -385,6 +385,9 @@ var FileAuditStore = class {
     const digest = sha256(stableStringify({ decisionId: decision.decisionId, status: decision.status, request: decision.request, violatedRule: decision.violatedRule ?? null }));
     const hash = sha256(`${prevHash}|${digest}|${seq}|${ts}`);
     const record2 = { seq, decisionId: decision.decisionId, status: decision.status, subject: decision.subject, digest, prevHash, hash, ts };
+    if (typeof decision.request?.purpose === "string" && decision.request.purpose.trim()) {
+      record2.purpose = decision.request.purpose.slice(0, 500);
+    }
     if (decision.status === "ALLOW") {
       const req = decision.request;
       if (typeof req?.amount === "number" && Number.isFinite(req.amount))
@@ -457,6 +460,10 @@ var GrantEnforcingExecutor = class {
     this.rail = rail;
     this.pub = createPublicKey(publicKeyPem2);
     this.redeem = opts?.redeem;
+    const isProd = typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+    if (isProd && !this.redeem && !opts?.allowUnsafeInMemorySingleUse) {
+      throw new Error("GrantEnforcingExecutor in production requires a durable `redeem` (single-use across instances). Wire httpRedeem(coreUrl, apiKey), or pass allowUnsafeInMemorySingleUse:true only for a true single-process deployment.");
+    }
   }
   async execute(req, grant) {
     if (!grant)
@@ -587,7 +594,25 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.1.17" : "dev";
+var CLIENT_VERSION = true ? "0.1.19" : "dev";
+function bandOf(amount) {
+  if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
+  if (amount < 10) return "lt10";
+  if (amount < 100) return "10_99";
+  if (amount < 1e3) return "100_999";
+  if (amount < 1e4) return "1k_10k";
+  if (amount < 1e5) return "10k_100k";
+  return "gte100k";
+}
+function capRatioOf(amount, perTxMax) {
+  if (typeof amount !== "number" || typeof perTxMax !== "number") return void 0;
+  if (!Number.isFinite(amount) || !Number.isFinite(perTxMax) || perTxMax <= 0 || amount <= perTxMax) return void 0;
+  const r = amount / perTxMax;
+  if (r < 2) return "1_2x";
+  if (r < 5) return "2_5x";
+  if (r < 10) return "5_10x";
+  return "gt10x";
+}
 var currentShell = "mcp";
 function setTelemetryShell(shell) {
   currentShell = shell;
@@ -620,9 +645,17 @@ function resultOf(status, violatedRule) {
   if (r.startsWith("non_positive_amount") || r.startsWith("invalid_")) return "deny_invalid";
   return "deny_scope";
 }
-function record(type, result) {
+function record(type, result, band, capRatio) {
   if (!telemetryEnabled()) return;
-  buffer.push({ type, ts: (/* @__PURE__ */ new Date()).toISOString(), client_version: CLIENT_VERSION, shell: currentShell, ...result ? { result } : {} });
+  buffer.push({
+    type,
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    client_version: CLIENT_VERSION,
+    shell: currentShell,
+    ...result ? { result } : {},
+    ...band ? { band } : {},
+    ...capRatio ? { cap_ratio: capRatio } : {}
+  });
   if (!flushTimer) {
     flushTimer = setTimeout(() => {
       void flush();
@@ -632,7 +665,7 @@ function record(type, result) {
 }
 var recordInstall = () => record("install");
 var recordAgentActive = () => record("agent_active");
-var recordDecision = (status, violatedRule) => record("decision", resultOf(status, violatedRule));
+var recordDecision = (status, violatedRule, amount, perTxMax) => record("decision", resultOf(status, violatedRule), bandOf(amount), capRatioOf(amount, perTxMax));
 var recordUpgradeIntent = () => record("upgrade_intent");
 async function flush() {
   if (flushTimer) {
@@ -695,10 +728,11 @@ function makeCore() {
     if (!url || !key) throw new Error("FIDACY_MODE=http requires FIDACY_API_URL and FIDACY_API_KEY");
     return new HttpFidacyCore(url, key, process.env.FIDACY_PUBLIC_KEY_PEM ?? "");
   }
+  let activeMandate = buildMandate();
   const dev = new DevFidacyCore({
-    mandate: buildMandate(),
+    mandate: activeMandate,
     auditLogPath: auditLogPath(),
-    onDecision: (d) => recordDecision(d.status, d.violatedRule)
+    onDecision: (d) => recordDecision(d.status, d.violatedRule, d.request?.amount, activeMandate?.allow?.perTxMax)
   });
   const mtimeOf = () => statSync(configPath(), { throwIfNoEntry: false })?.mtimeMs ?? 0;
   let seenMtime = mtimeOf();
@@ -706,7 +740,8 @@ function makeCore() {
     const m = mtimeOf();
     if (m !== seenMtime) {
       seenMtime = m;
-      dev.setMandate(buildMandate());
+      activeMandate = buildMandate();
+      dev.setMandate(activeMandate);
     }
   };
   return {
@@ -736,7 +771,7 @@ function requestUpgrade() {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.1.17" : "dev";
+var CLIENT_VERSION2 = true ? "0.1.19" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidacy/mcp",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Fidacy action firewall for AI agents. Mandate-gated payment authorization as an MCP server.",
   "license": "Apache-2.0",
   "homepage": "https://fidacy.com",