@fidacy/mcp 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -74,3 +74,24 @@ semantic versioning.
 - One install delivers both the signed verdict (assess_action) and the
   non-custodial payment firewall (request_payment), with the same signed,
   publicly verifiable proof as the SDK.
+
+## 0.1.10 — 2026-07-02
+
+- Telemetry: `shell` channel attribution (mcp | openclaw-plugin | crabtrap | sdk)
+  and `client_version` injected from package.json at build time (0.1.5 had shipped
+  stale through 0.1.9 in telemetry AND provision).
+- DENY responses now point to the `upgrade` tool (free account, signed anchored
+  proof of every block).
+- Onboarding: first-run `~/.fidacy/config.json` now writes the mandate template
+  explicitly (payees/categories/currency/caps) — adding a trusted payee is a
+  visible one-line edit; friendlier first-boot message (no more "dev mode" scare).
+
+## 0.1.11 — 2026-07-02
+
+- Upgrade micro-triggers, elegant by doctrine: fire only at value-proven moments
+  (first block, first duplicate-invoice/BEC catch, 10th gated action, one week
+  protected), each ONCE per install ever (persisted in config.json) — the free
+  tier stays fully usable in silence. The 0.1.10 every-DENY nudge is replaced.
+- verify_mandate/get_audit_proof gain one informational closing line each;
+  assess_action's missing-key error now offers the free-key path.
+- config.json gains created_at + nudge/decision state (preserved on read).

package/dist/core.js

@@ -213,7 +213,7 @@ var DevFidacyCore = class {
     this.priv = kp.privateKey;
     this.pubPem = publicKeyPem(kp.publicKey);
     if (kp.ephemeral)
-      console.error("[fidacy] dev mode: ephemeral signing key. Production: set FIDACY_SIGNING_KEY_B64, or FIDACY_MODE=http + FIDACY_API_URL + FIDACY_API_KEY to use the live core.");
+      console.error("[fidacy] local firewall active, deny-by-default. Grants are signed with a per-session key (fine for local use); set FIDACY_SIGNING_KEY_B64 for a stable key, or FIDACY_MODE=http to use the hosted core.");
     this.mandate = opts.mandate;
     this.store = new FileAuditStore(opts.auditLogPath ?? "./fidacy-audit.log");
     this.onDecision = opts.onDecision;
@@ -337,7 +337,12 @@ function readConfig() {
       anon_id: raw.anon_id,
       tier: raw.tier === "paid" ? "paid" : "free",
       api_key: typeof raw.api_key === "string" ? raw.api_key : null,
-      mandate: raw.mandate
+      mandate: raw.mandate,
+      // Install-state passthrough: dropping these on a read→write cycle would
+      // reset every once-per-install nudge into an every-time nag.
+      created_at: typeof raw.created_at === "string" ? raw.created_at : void 0,
+      nudges: raw.nudges && typeof raw.nudges === "object" ? raw.nudges : void 0,
+      decisions_count: typeof raw.decisions_count === "number" ? raw.decisions_count : void 0
     };
   } catch {
     return null;
@@ -357,7 +362,8 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = "0.1.5";
+var CLIENT_VERSION = true ? "0.1.11" : "dev";
+var currentShell = "mcp";
 function telemetryEnabled() {
   const v = (process.env.FIDACY_DISABLE_TELEMETRY ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -383,7 +389,7 @@ function resultOf(status, violatedRule) {
 }
 function record(type, result) {
   if (!telemetryEnabled()) return;
-  buffer.push({ type, ts: (/* @__PURE__ */ new Date()).toISOString(), client_version: CLIENT_VERSION, ...result ? { result } : {} });
+  buffer.push({ type, ts: (/* @__PURE__ */ new Date()).toISOString(), client_version: CLIENT_VERSION, shell: currentShell, ...result ? { result } : {} });
   if (!flushTimer) {
     flushTimer = setTimeout(() => {
       void flush();

package/dist/index.js

@@ -220,7 +220,7 @@ var DevFidacyCore = class {
     this.priv = kp.privateKey;
     this.pubPem = publicKeyPem(kp.publicKey);
     if (kp.ephemeral)
-      console.error("[fidacy] dev mode: ephemeral signing key. Production: set FIDACY_SIGNING_KEY_B64, or FIDACY_MODE=http + FIDACY_API_URL + FIDACY_API_KEY to use the live core.");
+      console.error("[fidacy] local firewall active, deny-by-default. Grants are signed with a per-session key (fine for local use); set FIDACY_SIGNING_KEY_B64 for a stable key, or FIDACY_MODE=http to use the hosted core.");
     this.mandate = opts.mandate;
     this.store = new FileAuditStore(opts.auditLogPath ?? "./fidacy-audit.log");
     this.onDecision = opts.onDecision;
@@ -345,7 +345,12 @@ function readConfig() {
       anon_id: raw.anon_id,
       tier: raw.tier === "paid" ? "paid" : "free",
       api_key: typeof raw.api_key === "string" ? raw.api_key : null,
-      mandate: raw.mandate
+      mandate: raw.mandate,
+      // Install-state passthrough: dropping these on a read→write cycle would
+      // reset every once-per-install nudge into an every-time nag.
+      created_at: typeof raw.created_at === "string" ? raw.created_at : void 0,
+      nudges: raw.nudges && typeof raw.nudges === "object" ? raw.nudges : void 0,
+      decisions_count: typeof raw.decisions_count === "number" ? raw.decisions_count : void 0
     };
   } catch {
     return null;
@@ -359,7 +364,13 @@ function writeConfig(cfg) {
 function ensureState() {
   const existing = readConfig();
   if (existing) return { config: existing, firstRun: false };
-  const config = { anon_id: randomUUID2(), tier: "free", api_key: null };
+  const config = {
+    anon_id: randomUUID2(),
+    tier: "free",
+    api_key: null,
+    mandate: { payees: [], categories: ["*"], currency: "USD", perTxMax: 2500, maxTotal: 1e4 },
+    created_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
   try {
     writeConfig(config);
   } catch {
@@ -380,7 +391,8 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = "0.1.5";
+var CLIENT_VERSION = true ? "0.1.11" : "dev";
+var currentShell = "mcp";
 function telemetryEnabled() {
   const v = (process.env.FIDACY_DISABLE_TELEMETRY ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -406,7 +418,7 @@ function resultOf(status, violatedRule) {
 }
 function record(type, result) {
   if (!telemetryEnabled()) return;
-  buffer.push({ type, ts: (/* @__PURE__ */ new Date()).toISOString(), client_version: CLIENT_VERSION, ...result ? { result } : {} });
+  buffer.push({ type, ts: (/* @__PURE__ */ new Date()).toISOString(), client_version: CLIENT_VERSION, shell: currentShell, ...result ? { result } : {} });
   if (!flushTimer) {
     flushTimer = setTimeout(() => {
       void flush();
@@ -603,7 +615,7 @@ async function postOnce(fetchImpl, url, headers, payload, timeoutMs) {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = "0.1.5";
+var CLIENT_VERSION2 = true ? "0.1.11" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -650,6 +662,55 @@ function requestUpgrade() {
   return { url: upgradeUrl(), anonId: anonId2 };
 }
 
+// src/nudges.ts
+function nudgeOnce(key) {
+  const cfg = readConfig();
+  if (!cfg) return false;
+  if (cfg.nudges?.[key]) return false;
+  cfg.nudges = { ...cfg.nudges ?? {}, [key]: true };
+  try {
+    writeConfig(cfg);
+  } catch {
+    return false;
+  }
+  return true;
+}
+function bumpDecisionCount() {
+  const cfg = readConfig();
+  if (!cfg) return 0;
+  const n = (cfg.decisions_count ?? 0) + 1;
+  cfg.decisions_count = n;
+  try {
+    writeConfig(cfg);
+  } catch {
+  }
+  return n;
+}
+function installAgeDays() {
+  const t = Date.parse(readConfig()?.created_at ?? "");
+  if (Number.isNaN(t)) return 0;
+  return Math.floor((Date.now() - t) / 864e5);
+}
+function decisionNudge(status, violatedRule, upgradeToolName) {
+  const count = bumpDecisionCount();
+  if (status === "DENY" && violatedRule?.startsWith("duplicate_invoice") && nudgeOnce("bec_catch")) {
+    return `That was a duplicate-invoice (BEC) catch \u2014 the #1 payment fraud. On a free account every block like this is server-signed and anchored to Bitcoin: court-grade evidence. Call the ${upgradeToolName} tool to start.`;
+  }
+  if (status === "DENY" && nudgeOnce("first_deny")) {
+    return `Fidacy just blocked this for you \u2014 for server-signed, anchored proof of every block (free account, local history migrates), call the ${upgradeToolName} tool.`;
+  }
+  if (count === 10 && nudgeOnce("milestone_10")) {
+    return `That's 10 actions gated on this install. For a signed, Bitcoin-anchored history of all of them (free account), call the ${upgradeToolName} tool.`;
+  }
+  return null;
+}
+function weekOneBootNudge(upgradeToolName) {
+  if (installAgeDays() >= 7 && nudgeOnce("week_1")) {
+    return ` One week protected \u2014 anchor your history to Bitcoin with a free account: the ${upgradeToolName} tool starts it.`;
+  }
+  return null;
+}
+
 // src/index.ts
 var state = ensureState();
 var core = makeCore();
@@ -683,8 +744,10 @@ server.registerTool(
     const req = args;
     const d = await core.decide(req, subject);
     const out = { status: d.status, decisionId: d.decisionId, grant: d.grant, violatedRule: d.violatedRule };
-    const human = 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:
+    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.`;
+    const nudge = decisionNudge(d.status, d.violatedRule, "upgrade");
+    const human = nudge ? `${base} ${nudge}` : base;
     return { content: [{ type: "text", text: human }], structuredContent: out };
   }
 );
@@ -699,7 +762,8 @@ server.registerTool(
   async () => {
     const m = await core.getMandate(subject);
     const payload = { mandate: m, fidacyPublicKey: core.publicKey() };
-    return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], structuredContent: payload };
+    const text = JSON.stringify(payload, null, 2) + "\n\nThis mandate is local (free tier). Hosted mandates add team governance and server-signed verdicts \u2014 the upgrade tool starts a free account.";
+    return { content: [{ type: "text", text }], structuredContent: payload };
   }
 );
 server.registerTool(
@@ -713,7 +777,8 @@ server.registerTool(
   async ({ decisionId }) => {
     const proof = await core.getProof(decisionId);
     if (!proof) return { content: [{ type: "text", text: `No proof found for ${decisionId}` }], isError: true };
-    return { content: [{ type: "text", text: JSON.stringify(proof, null, 2) }], structuredContent: proof };
+    const text = JSON.stringify(proof, null, 2) + "\n\nThis proof lives on this machine. On a free hosted account the chain is anchored to Bitcoin \u2014 verifiable by anyone, forever, even against Fidacy (the upgrade tool starts it).";
+    return { content: [{ type: "text", text }], structuredContent: proof };
   }
 );
 server.registerTool(
@@ -739,7 +804,7 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: "assess_action requires FIDACY_ENGINE_API_KEY (an fky_live_/fky_test_ key with assess:write). Set it to enable signed verdicts."
+            text: "assess_action needs an engine key \u2014 free in about a minute: call the upgrade tool (your usage history migrates), or set FIDACY_ENGINE_API_KEY if you already have one."
           }
         ],
         isError: true
@@ -799,7 +864,8 @@ async function main() {
   void autoProvision();
   const verdictHint = process.env.FIDACY_ENGINE_API_KEY ? "" : " Set FIDACY_ENGINE_API_KEY to enable verdicts (assess_action).";
   const tierHint = state.firstRun ? " First run: free local tier active (deny-unknown payee + cap). Add trusted payees in ~/.fidacy/config.json." : ` Tier: ${state.config.tier} (local-first).`;
-  console.error("[fidacy] @fidacy/mcp ready on stdio: signed verdict + payment firewall." + tierHint + verdictHint);
+  const weekNudge = weekOneBootNudge("upgrade") ?? "";
+  console.error("[fidacy] @fidacy/mcp ready on stdio: signed verdict + payment firewall." + tierHint + verdictHint + weekNudge);
 }
 main().catch((e) => {
   console.error("[fidacy] fatal:", e);

package/dist/lib.js

@@ -339,7 +339,7 @@ var DevFidacyCore = class {
     this.priv = kp.privateKey;
     this.pubPem = publicKeyPem(kp.publicKey);
     if (kp.ephemeral)
-      console.error("[fidacy] dev mode: ephemeral signing key. Production: set FIDACY_SIGNING_KEY_B64, or FIDACY_MODE=http + FIDACY_API_URL + FIDACY_API_KEY to use the live core.");
+      console.error("[fidacy] local firewall active, deny-by-default. Grants are signed with a per-session key (fine for local use); set FIDACY_SIGNING_KEY_B64 for a stable key, or FIDACY_MODE=http to use the hosted core.");
     this.mandate = opts.mandate;
     this.store = new FileAuditStore(opts.auditLogPath ?? "./fidacy-audit.log");
     this.onDecision = opts.onDecision;
@@ -430,6 +430,7 @@ var HttpFidacyCore = class {
 };
 
 // src/config.ts
+import { randomUUID as randomUUID3 } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import {
@@ -463,12 +464,38 @@ function readConfig() {
       anon_id: raw.anon_id,
       tier: raw.tier === "paid" ? "paid" : "free",
       api_key: typeof raw.api_key === "string" ? raw.api_key : null,
-      mandate: raw.mandate
+      mandate: raw.mandate,
+      // Install-state passthrough: dropping these on a read→write cycle would
+      // reset every once-per-install nudge into an every-time nag.
+      created_at: typeof raw.created_at === "string" ? raw.created_at : void 0,
+      nudges: raw.nudges && typeof raw.nudges === "object" ? raw.nudges : void 0,
+      decisions_count: typeof raw.decisions_count === "number" ? raw.decisions_count : void 0
     };
   } catch {
     return null;
   }
 }
+function writeConfig(cfg) {
+  const dir = configDir();
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  writeFileSync(configPath(), JSON.stringify(cfg, null, 2), { mode: 384 });
+}
+function ensureState() {
+  const existing = readConfig();
+  if (existing) return { config: existing, firstRun: false };
+  const config = {
+    anon_id: randomUUID3(),
+    tier: "free",
+    api_key: null,
+    mandate: { payees: [], categories: ["*"], currency: "USD", perTxMax: 2500, maxTotal: 1e4 },
+    created_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  try {
+    writeConfig(config);
+  } catch {
+  }
+  return { config, firstRun: true };
+}
 function resolveMandateRules(cfg) {
   const m = cfg?.mandate ?? {};
   const envList = (v) => v === void 0 ? void 0 : v.split(",").map((s) => s.trim()).filter(Boolean);
@@ -483,7 +510,11 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = "0.1.5";
+var CLIENT_VERSION = true ? "0.1.11" : "dev";
+var currentShell = "mcp";
+function setTelemetryShell(shell) {
+  currentShell = shell;
+}
 function telemetryEnabled() {
   const v = (process.env.FIDACY_DISABLE_TELEMETRY ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -509,7 +540,7 @@ function resultOf(status, violatedRule) {
 }
 function record(type, result) {
   if (!telemetryEnabled()) return;
-  buffer.push({ type, ts: (/* @__PURE__ */ new Date()).toISOString(), client_version: CLIENT_VERSION, ...result ? { result } : {} });
+  buffer.push({ type, ts: (/* @__PURE__ */ new Date()).toISOString(), client_version: CLIENT_VERSION, shell: currentShell, ...result ? { result } : {} });
   if (!flushTimer) {
     flushTimer = setTimeout(() => {
       void flush();
@@ -517,7 +548,10 @@ function record(type, result) {
     if (typeof flushTimer.unref === "function") flushTimer.unref();
   }
 }
+var recordInstall = () => record("install");
+var recordAgentActive = () => record("agent_active");
 var recordDecision = (status, violatedRule) => record("decision", resultOf(status, violatedRule));
+var recordUpgradeIntent = () => record("upgrade_intent");
 async function flush() {
   if (flushTimer) {
     clearTimeout(flushTimer);
@@ -585,24 +619,133 @@ function makeCore() {
     onDecision: (d) => recordDecision(d.status, d.violatedRule)
   });
 }
+
+// src/upgrade.ts
+function upgradeUrl() {
+  const base = (process.env.FIDACY_APP_URL ?? "https://app.fidacy.com").replace(/\/$/, "");
+  const anon = readConfig()?.anon_id ?? "";
+  return `${base}/upgrade?anon=${encodeURIComponent(anon)}`;
+}
+function requestUpgrade() {
+  recordUpgradeIntent();
+  const anonId2 = readConfig()?.anon_id ?? "";
+  return { url: upgradeUrl(), anonId: anonId2 };
+}
+
+// src/provision.ts
+var CLIENT_VERSION2 = true ? "0.1.11" : "dev";
+function provisionEnabled() {
+  const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
+  return !(v === "1" || v === "true" || v === "yes");
+}
+function endpoint2() {
+  const base = (process.env.FIDACY_ENGINE_URL ?? "https://api.fidacy.com").replace(/\/$/, "");
+  return `${base}/v1/provision`;
+}
+async function autoProvision() {
+  if (!provisionEnabled()) return "skipped";
+  const cfg = readConfig();
+  if (!cfg) return "skipped";
+  if (cfg.api_key) return "skipped";
+  try {
+    const res = await fetch(endpoint2(), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ anon_id: cfg.anon_id, client_version: CLIENT_VERSION2 })
+    });
+    if (res.status === 429) return "rate_limited";
+    if (!res.ok) return "failed";
+    const data = await res.json();
+    if (typeof data.api_key !== "string" || !data.api_key) return "failed";
+    writeConfig({
+      ...cfg,
+      api_key: data.api_key,
+      tier: data.tier === "paid" ? "paid" : "free"
+    });
+    return "provisioned";
+  } catch {
+    return "failed";
+  }
+}
+
+// src/nudges.ts
+function nudgeOnce(key) {
+  const cfg = readConfig();
+  if (!cfg) return false;
+  if (cfg.nudges?.[key]) return false;
+  cfg.nudges = { ...cfg.nudges ?? {}, [key]: true };
+  try {
+    writeConfig(cfg);
+  } catch {
+    return false;
+  }
+  return true;
+}
+function bumpDecisionCount() {
+  const cfg = readConfig();
+  if (!cfg) return 0;
+  const n = (cfg.decisions_count ?? 0) + 1;
+  cfg.decisions_count = n;
+  try {
+    writeConfig(cfg);
+  } catch {
+  }
+  return n;
+}
+function installAgeDays() {
+  const t = Date.parse(readConfig()?.created_at ?? "");
+  if (Number.isNaN(t)) return 0;
+  return Math.floor((Date.now() - t) / 864e5);
+}
+function decisionNudge(status, violatedRule, upgradeToolName) {
+  const count = bumpDecisionCount();
+  if (status === "DENY" && violatedRule?.startsWith("duplicate_invoice") && nudgeOnce("bec_catch")) {
+    return `That was a duplicate-invoice (BEC) catch \u2014 the #1 payment fraud. On a free account every block like this is server-signed and anchored to Bitcoin: court-grade evidence. Call the ${upgradeToolName} tool to start.`;
+  }
+  if (status === "DENY" && nudgeOnce("first_deny")) {
+    return `Fidacy just blocked this for you \u2014 for server-signed, anchored proof of every block (free account, local history migrates), call the ${upgradeToolName} tool.`;
+  }
+  if (count === 10 && nudgeOnce("milestone_10")) {
+    return `That's 10 actions gated on this install. For a signed, Bitcoin-anchored history of all of them (free account), call the ${upgradeToolName} tool.`;
+  }
+  return null;
+}
+function weekOneBootNudge(upgradeToolName) {
+  if (installAgeDays() >= 7 && nudgeOnce("week_1")) {
+    return ` One week protected \u2014 anchor your history to Bitcoin with a free account: the ${upgradeToolName} tool starts it.`;
+  }
+  return null;
+}
 export {
   DevFidacyCore,
   FileAuditStore,
   GrantEnforcingExecutor,
   HttpFidacyCore,
   ReferenceRail,
+  autoProvision,
   canonInvoice,
+  decisionNudge,
+  ensureState,
   evaluate,
   httpRedeem,
+  installAgeDays,
   loadOrGenerateKeyPair,
   lookalikePayee,
   makeCore,
+  nudgeOnce,
   publicKeyPem,
+  readConfig,
+  recordAgentActive,
+  recordInstall,
+  requestUpgrade,
   requireHttpsBase,
+  setTelemetryShell,
   sha256,
   sign,
   stableStringify,
+  upgradeUrl,
   validateRequest,
   verify,
-  verifyGrant
+  verifyGrant,
+  weekOneBootNudge
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidacy/mcp",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Fidacy action firewall for AI agents. Mandate-gated payment authorization as an MCP server.",
   "license": "Apache-2.0",
   "homepage": "https://fidacy.com",
@@ -36,12 +36,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "node scripts/bundle.mjs",
-    "dev": "tsx watch src/index.ts",
-    "start": "node dist/index.js",
-    "prepublishOnly": "npm run build"
-  },
   "engines": {
     "node": ">=18"
   },
@@ -50,14 +44,19 @@
     "zod": "^3.25.0"
   },
   "devDependencies": {
-    "@fidacy/firewall": "workspace:*",
     "@types/node": "^22.10.0",
     "tsx": "^4.19.2",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "@fidacy/firewall": "0.1.0"
   },
   "mcpName": "com.fidacy/mcp",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lucaslubi/fidacy-mcp.git"
+  },
+  "scripts": {
+    "build": "node scripts/bundle.mjs",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js"
   }
-}
+}