@fidacy/mcp 0.1.16 → 0.1.18

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to `@fidacy/mcp` are documented here. This project follows
 semantic versioning.
 
+## 0.1.17 — 2026-07-03
+
+- Config HOT-RELOAD: editing `~/.fidacy/config.json` (payees, caps) takes effect
+  on the next call, no host restart. Spend and invoice-dedup state is rebuilt
+  from the audit log on reload, so a reload never weakens the firewall.
+- The `payee_not_in_allowlist` DENY now tells the agent exactly how to allow a
+  trusted payee (friction fix from a clean-room install test).
+
 ## 0.1.16 — 2026-07-03
 
 - `anchor_artifact`/`check_artifact`: new kind `conversation` — anchor chatbot

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

@@ -1,3 +1,6 @@
+// src/core.ts
+import { statSync } from "node:fs";
+
 // ../firewall/dist/util.js
 function stableStringify(obj) {
   if (obj === null || typeof obj !== "object")
@@ -189,6 +192,19 @@ var DevFidacyCore = class {
       this.spent += r.amount;
     }
   }
+  /**
+   * Swap the active mandate (shell config hot-reload: edit config.json, the next
+   * call picks it up, no host restart). Decision state is REBUILT from the audit
+   * log under the new window/currency, so a reload can never reset the BEC
+   * invoice dedup or undercount spend: a paid invoice stays paid, spent is
+   * recomputed.
+   */
+  setMandate(m) {
+    this.mandate = m;
+    this.spent = 0;
+    this.claimedInvoices.clear();
+    this.rehydrate();
+  }
   async getMandate() {
     return this.mandate;
   }
@@ -331,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))
@@ -423,7 +442,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.1.16" : "dev";
+var CLIENT_VERSION = true ? "0.1.18" : "dev";
 var currentShell = "mcp";
 function telemetryEnabled() {
   const v = (process.env.FIDACY_DISABLE_TELEMETRY ?? "").trim().toLowerCase();
@@ -525,11 +544,32 @@ 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 ?? "");
   }
-  return new DevFidacyCore({
+  const dev = new DevFidacyCore({
     mandate: buildMandate(),
     auditLogPath: auditLogPath(),
     onDecision: (d) => recordDecision(d.status, d.violatedRule)
   });
+  const mtimeOf = () => statSync(configPath(), { throwIfNoEntry: false })?.mtimeMs ?? 0;
+  let seenMtime = mtimeOf();
+  const maybeReload = () => {
+    const m = mtimeOf();
+    if (m !== seenMtime) {
+      seenMtime = m;
+      dev.setMandate(buildMandate());
+    }
+  };
+  return {
+    getMandate: () => {
+      maybeReload();
+      return dev.getMandate();
+    },
+    decide: (req, subject) => {
+      maybeReload();
+      return dev.decide(req, subject);
+    },
+    getProof: (decisionId) => dev.getProof(decisionId),
+    publicKey: () => dev.publicKey()
+  };
 }
 export {
   makeCore

package/dist/index.js

@@ -5,6 +5,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 
+// src/core.ts
+import { statSync } from "node:fs";
+
 // ../firewall/dist/util.js
 function stableStringify(obj) {
   if (obj === null || typeof obj !== "object")
@@ -196,6 +199,19 @@ var DevFidacyCore = class {
       this.spent += r.amount;
     }
   }
+  /**
+   * Swap the active mandate (shell config hot-reload: edit config.json, the next
+   * call picks it up, no host restart). Decision state is REBUILT from the audit
+   * log under the new window/currency, so a reload can never reset the BEC
+   * invoice dedup or undercount spend: a paid invoice stays paid, spent is
+   * recomputed.
+   */
+  setMandate(m) {
+    this.mandate = m;
+    this.spent = 0;
+    this.claimedInvoices.clear();
+    this.rehydrate();
+  }
   async getMandate() {
     return this.mandate;
   }
@@ -338,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))
@@ -452,7 +471,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.1.16" : "dev";
+var CLIENT_VERSION = true ? "0.1.18" : "dev";
 var currentShell = "mcp";
 function telemetryEnabled() {
   const v = (process.env.FIDACY_DISABLE_TELEMETRY ?? "").trim().toLowerCase();
@@ -557,11 +576,32 @@ 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 ?? "");
   }
-  return new DevFidacyCore({
+  const dev = new DevFidacyCore({
     mandate: buildMandate(),
     auditLogPath: auditLogPath(),
     onDecision: (d) => recordDecision(d.status, d.violatedRule)
   });
+  const mtimeOf = () => statSync(configPath(), { throwIfNoEntry: false })?.mtimeMs ?? 0;
+  let seenMtime = mtimeOf();
+  const maybeReload = () => {
+    const m = mtimeOf();
+    if (m !== seenMtime) {
+      seenMtime = m;
+      dev.setMandate(buildMandate());
+    }
+  };
+  return {
+    getMandate: () => {
+      maybeReload();
+      return dev.getMandate();
+    },
+    decide: (req, subject2) => {
+      maybeReload();
+      return dev.decide(req, subject2);
+    },
+    getProof: (decisionId) => dev.getProof(decisionId),
+    publicKey: () => dev.publicKey()
+  };
 }
 
 // src/assess.ts
@@ -654,7 +694,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 {
@@ -746,7 +786,7 @@ async function findArtifacts(sha2562, cfg) {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.1.16" : "dev";
+var CLIENT_VERSION2 = true ? "0.1.18" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -846,7 +886,7 @@ function weekOneBootNudge(upgradeToolName) {
 var state = ensureState();
 var core = makeCore();
 var subject = process.env.FIDACY_SUBJECT ?? "agent:demo";
-var SERVER_VERSION = true ? "0.1.16" : "dev";
+var SERVER_VERSION = true ? "0.1.18" : "dev";
 var server = new McpServer({ name: "fidacy", version: SERVER_VERSION });
 server.registerTool(
   "request_payment",
@@ -857,7 +897,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(
@@ -877,7 +919,7 @@ server.registerTool(
     const d = await core.decide(req, subject);
     const out = { status: d.status, decisionId: d.decisionId, grant: d.grant, violatedRule: d.violatedRule };
     const base = d.status === "ALLOW" ? `ALLOW (decision ${d.decisionId})${req.invoiceRef ? ` for invoice ${req.invoiceRef}` : ""}. To settle, call execute_payment with the SAME payee, amount, currency, and idempotencyKey, and set "grant" to EXACTLY this signed value:
-${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}. No grant issued, this payment cannot proceed. The denial itself is recorded in the tamper-evident, hash-chained audit: call get_audit_proof with decisionId ${d.decisionId} for the proof of what was blocked.`;
+${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}. No grant issued, this payment cannot proceed. The denial itself is recorded in the tamper-evident, hash-chained audit: call get_audit_proof with decisionId ${d.decisionId} for the proof of what was blocked.${d.violatedRule?.startsWith("payee_not_in_allowlist") ? ` If the user trusts this payee, add "${req.payee}" to mandate.payees in ~/.fidacy/config.json and retry: the firewall picks the change up on the next call, no restart needed.` : ""}`;
     const nudge = decisionNudge(d.status, d.violatedRule, "upgrade");
     const human = nudge ? `${base} ${nudge}` : base;
     return { content: [{ type: "text", text: human }], structuredContent: out };

package/dist/lib.js

@@ -230,6 +230,19 @@ var DevFidacyCore = class {
       this.spent += r.amount;
     }
   }
+  /**
+   * Swap the active mandate (shell config hot-reload: edit config.json, the next
+   * call picks it up, no host restart). Decision state is REBUILT from the audit
+   * log under the new window/currency, so a reload can never reset the BEC
+   * invoice dedup or undercount spend: a paid invoice stays paid, spent is
+   * recomputed.
+   */
+  setMandate(m) {
+    this.mandate = m;
+    this.spent = 0;
+    this.claimedInvoices.clear();
+    this.rehydrate();
+  }
   async getMandate() {
     return this.mandate;
   }
@@ -372,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))
@@ -444,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)
@@ -490,6 +510,9 @@ var GrantEnforcingExecutor = class {
   }
 };
 
+// src/core.ts
+import { statSync } from "node:fs";
+
 // src/config.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
 import { homedir } from "node:os";
@@ -571,7 +594,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.1.16" : "dev";
+var CLIENT_VERSION = true ? "0.1.18" : "dev";
 var currentShell = "mcp";
 function setTelemetryShell(shell) {
   currentShell = shell;
@@ -679,11 +702,32 @@ 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 ?? "");
   }
-  return new DevFidacyCore({
+  const dev = new DevFidacyCore({
     mandate: buildMandate(),
     auditLogPath: auditLogPath(),
     onDecision: (d) => recordDecision(d.status, d.violatedRule)
   });
+  const mtimeOf = () => statSync(configPath(), { throwIfNoEntry: false })?.mtimeMs ?? 0;
+  let seenMtime = mtimeOf();
+  const maybeReload = () => {
+    const m = mtimeOf();
+    if (m !== seenMtime) {
+      seenMtime = m;
+      dev.setMandate(buildMandate());
+    }
+  };
+  return {
+    getMandate: () => {
+      maybeReload();
+      return dev.getMandate();
+    },
+    decide: (req, subject) => {
+      maybeReload();
+      return dev.decide(req, subject);
+    },
+    getProof: (decisionId) => dev.getProof(decisionId),
+    publicKey: () => dev.publicKey()
+  };
 }
 
 // src/upgrade.ts
@@ -699,7 +743,7 @@ function requestUpgrade() {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.1.16" : "dev";
+var CLIENT_VERSION2 = true ? "0.1.18" : "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.16",
+  "version": "0.1.18",
   "description": "Fidacy action firewall for AI agents. Mandate-gated payment authorization as an MCP server.",
   "license": "Apache-2.0",
   "homepage": "https://fidacy.com",