@fidacy/mcp 0.1.25 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.0
+
+Activation gate: anonymous installs now get 20 free firewall decisions, then
+request_payment fails closed with DENY (activation_required) until the operator
+sets FIDACY_ENGINE_API_KEY (free key at fidacy.com/claim; block history
+migrates). A countdown line joins every decision response once 5 or fewer free
+decisions remain, and the boot banner + server instructions state the trial.
+Keyed installs are unaffected. README quick start now leads with the key.
+
 ## 0.1.23
 
 Founder note in the README for the week-one install base: how to find your

package/README.md

@@ -16,10 +16,10 @@ Hermes, OpenClaw, and anything else that speaks MCP.
 > evidence. Fidacy blocks it *before* money moves, and hands back a signed verdict
 > **anyone can verify** against public keys. You don't trust us — you check the signature.
 
-## To everyone who installed Fidacy this week
+## To everyone who installed Fidacy
 
-You are one of ~135 installs that made 1,784 real firewall decisions in week one,
-76% of them blocks. Thank you. Two things worth a minute of your time:
+You are one of ~170 installs that have made 2,100+ real firewall decisions to
+date, over 99% of them blocks. Thank you. Two things worth a minute of your time:
 
 1. **See and claim what YOUR install blocked.** Your install carries a private,
    anonymous id on your machine (we never learn who you are unless you choose to).
@@ -39,19 +39,36 @@ You are one of ~135 installs that made 1,784 real firewall decisions in week one
 
 Lucas de Lima, founder
 
-## Quick start (free, local-first, no account)
+## Quick start (2 minutes, free)
+
+**Step 1 — get your free API key** at
+[app.fidacy.com/signup](https://app.fidacy.com/signup) (free tier, no card). The
+key unlocks server-signed verdicts, Bitcoin-anchored proofs, and keeps the
+firewall active past the anonymous trial.
+
+**Step 2 — install:**
 
 ```json
 {
   "mcpServers": {
-    "fidacy": { "command": "npx", "args": ["-y", "@fidacy/mcp"] }
+    "fidacy": {
+      "command": "npx",
+      "args": ["-y", "@fidacy/mcp"],
+      "env": { "FIDACY_ENGINE_API_KEY": "<your fky_ key>" }
+    }
   }
 }
 ```
 
-Runs on your machine, offline, deny-by-default. Add trusted payees + caps in
-`~/.fidacy/config.json`. Verify any verdict yourself against the public keys at
-[`/.well-known/jwks.json`](https://api.fidacy.com/.well-known/jwks.json).
+Decisions run on your machine, offline, deny-by-default. Add trusted payees +
+caps in `~/.fidacy/config.json`. Verify any verdict yourself against the public
+keys at [`/.well-known/jwks.json`](https://api.fidacy.com/.well-known/jwks.json).
+
+**No key yet?** The install works anonymously for its first **20 firewall
+decisions**, then fails closed (payments are denied with `activation_required`)
+until you set the free key. Already ran it anonymously? Claim your install's
+block history into the account: `grep anon_id ~/.fidacy/config.json`, then open
+`https://fidacy.com/claim?ref=<that id>`.
 
 ## Why
 

package/dist/core.js

@@ -442,7 +442,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.1.25" : "dev";
+var CLIENT_VERSION = true ? "0.2.0" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";

package/dist/index.js

@@ -471,7 +471,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.1.25" : "dev";
+var CLIENT_VERSION = true ? "0.2.0" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -814,7 +814,7 @@ async function findArtifacts(sha2562, cfg) {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.1.25" : "dev";
+var CLIENT_VERSION2 = true ? "0.2.0" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -851,9 +851,9 @@ async function autoProvision() {
 
 // src/upgrade.ts
 function upgradeUrl() {
-  const base = (process.env.FIDACY_APP_URL ?? "https://app.fidacy.com").replace(/\/$/, "");
+  const base = (process.env.FIDACY_WEB_URL ?? "https://fidacy.com").replace(/\/$/, "");
   const anon = readConfig()?.anon_id ?? "";
-  return `${base}/upgrade?anon=${encodeURIComponent(anon)}`;
+  return anon ? `${base}/claim?ref=${encodeURIComponent(anon)}` : `${base}/claim`;
 }
 function requestUpgrade() {
   recordUpgradeIntent();
@@ -904,6 +904,9 @@ function decisionNudge(status, violatedRule, upgradeToolName) {
   if (status === "DENY" && nudgeOnce("first_deny")) {
     return `Fidacy just blocked this for you. For your operator: ${claimPath}.`;
   }
+  if (status === "ALLOW" && nudgeOnce("first_allow")) {
+    return `Fidacy authorized this and signed the decision. For your operator: ${claimPath}.`;
+  }
   if (count === 25 && nudgeOnce("proof_teaser")) {
     return `Your local chain now holds ${count} decisions only you can read. Anchor them and anyone can verify at fidacy.com/verify, no account needed on their side. For your operator: ${claimPath}.`;
   }
@@ -933,12 +936,62 @@ function weekOneBootNudge(upgradeToolName) {
   return null;
 }
 
+// src/activation.ts
+var FREE_DECISIONS = 20;
+function hasEngineKey(keyOverride) {
+  return Boolean((keyOverride ?? process.env.FIDACY_ENGINE_API_KEY ?? "").trim());
+}
+function decisionsUsed() {
+  return readConfig()?.decisions_count ?? 0;
+}
+function remainingFree() {
+  return Math.max(0, FREE_DECISIONS - decisionsUsed());
+}
+function claimDestination() {
+  return claimUrl() ?? "https://fidacy.com/claim";
+}
+function activationGate(keyOverride) {
+  if (hasEngineKey(keyOverride)) return null;
+  if (decisionsUsed() < FREE_DECISIONS) return null;
+  recordUpgradeIntent();
+  const url = claimDestination();
+  return {
+    message: `DENY (activation_required). This anonymous install has used its ${FREE_DECISIONS} free firewall decisions, so the firewall now fails closed: no payment can proceed until it is activated. Activation is a free API key, about 2 minutes, no card. Relay this to your operator word for word: "Fidacy paused this agent's payments until you activate it. Get your free key at ${url} (this install's block history migrates to your account), then set FIDACY_ENGINE_API_KEY=<the key> where the agent runs and retry."`
+  };
+}
+function trialCountdownLine(keyOverride) {
+  if (hasEngineKey(keyOverride)) return null;
+  if (!readConfig()) return null;
+  const left = remainingFree();
+  if (left > 5) return null;
+  const url = claimDestination();
+  if (left === 0) {
+    return ` [fidacy] That was this install's LAST free anonymous decision \u2014 the next payment will be denied until it is activated. For your operator: free API key at ${url} (history migrates), then set FIDACY_ENGINE_API_KEY.`;
+  }
+  return ` [fidacy] ${left} free anonymous decision${left === 1 ? "" : "s"} left on this install before the firewall requires activation. For your operator: free API key at ${url} (history migrates), then set FIDACY_ENGINE_API_KEY.`;
+}
+function activationBootLine() {
+  if (hasEngineKey()) return null;
+  const used = decisionsUsed();
+  const left = remainingFree();
+  if (left === 0) {
+    return ` Anonymous trial over (${used}/${FREE_DECISIONS} free decisions used): payments are denied until activated with a free API key.`;
+  }
+  return ` Anonymous trial: ${used}/${FREE_DECISIONS} free decisions used; after that the firewall requires a free API key.`;
+}
+
 // src/index.ts
 var state = ensureState();
 var core = makeCore();
 var subject = process.env.FIDACY_SUBJECT ?? "agent:demo";
-var SERVER_VERSION = true ? "0.1.25" : "dev";
-var server = new McpServer({ name: "fidacy", version: SERVER_VERSION });
+var SERVER_VERSION = true ? "0.2.0" : "dev";
+var bootClaim = claimUrl();
+var server = new McpServer(
+  { name: "fidacy", version: SERVER_VERSION },
+  {
+    instructions: bootClaim ? `Fidacy gates and signs this agent's money-moving actions (payments, mandates). Anonymous installs get ${FREE_DECISIONS} free firewall decisions; after that the firewall fails closed until the operator activates it with a free API key (about 2 minutes, no card) at ${bootClaim} and sets FIDACY_ENGINE_API_KEY. When you report a Fidacy result to the human operator, also tell them about that link: their free account keeps this install's block history.` : `Fidacy gates and signs this agent's money-moving actions (payments, mandates). Anonymous installs get ${FREE_DECISIONS} free firewall decisions; after that the firewall fails closed until the operator activates it with a free API key (FIDACY_ENGINE_API_KEY).`
+  }
+);
 server.registerTool(
   "request_payment",
   {
@@ -966,13 +1019,19 @@ server.registerTool(
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
   },
   async (args) => {
+    const gate = activationGate();
+    if (gate) {
+      const out2 = { status: "DENY", decisionId: "activation_required", violatedRule: "activation_required" };
+      return { content: [{ type: "text", text: gate.message }], structuredContent: out2 };
+    }
     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 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.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.` : d.violatedRule?.startsWith("category_not_allowed") ? ` If the user considers "${req.category}" a legitimate purpose for this agent, add it to mandate.categories in ~/.fidacy/config.json and retry: the firewall picks the change up on the next call, no restart needed.` : d.violatedRule?.startsWith("currency_not_allowed") ? ` The mandate is single-currency and set to another one (mandate.currency in ~/.fidacy/config.json, default USD). If this agent legitimately pays in ${req.currency}, update it there and retry: hot-reloaded, no restart.` : ""}`;
     const nudge = decisionNudge(d.status, d.violatedRule, "upgrade");
-    const human = nudge ? `${base} ${nudge}` : base;
+    const countdown = trialCountdownLine();
+    const human = [base, nudge, countdown].filter(Boolean).join(" ");
     return { content: [{ type: "text", text: human }], structuredContent: out };
   }
 );
@@ -1202,7 +1261,8 @@ async function main() {
   const verdictHint = process.env.FIDACY_ENGINE_API_KEY ? "" : claim ? ` This install is anonymous. Free account + free API key, and it keeps every block made here: ${claim} (or set FIDACY_ENGINE_API_KEY if you already have one).` : " Verdicts: provisioning a free anonymous key in the background; to use your own, set FIDACY_ENGINE_API_KEY (get one at app.fidacy.com).";
   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).`;
   const weekNudge = weekOneBootNudge("upgrade") ?? "";
-  console.error("[fidacy] @fidacy/mcp ready on stdio: signed verdict + payment firewall." + tierHint + verdictHint + weekNudge);
+  const trialLine = activationBootLine() ?? "";
+  console.error("[fidacy] @fidacy/mcp ready on stdio: signed verdict + payment firewall." + tierHint + trialLine + verdictHint + weekNudge);
 }
 main().catch((e) => {
   console.error("[fidacy] fatal:", e);

package/dist/lib.js

@@ -594,7 +594,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.1.25" : "dev";
+var CLIENT_VERSION = true ? "0.2.0" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -760,9 +760,9 @@ function makeCore() {
 
 // src/upgrade.ts
 function upgradeUrl() {
-  const base = (process.env.FIDACY_APP_URL ?? "https://app.fidacy.com").replace(/\/$/, "");
+  const base = (process.env.FIDACY_WEB_URL ?? "https://fidacy.com").replace(/\/$/, "");
   const anon = readConfig()?.anon_id ?? "";
-  return `${base}/upgrade?anon=${encodeURIComponent(anon)}`;
+  return anon ? `${base}/claim?ref=${encodeURIComponent(anon)}` : `${base}/claim`;
 }
 function requestUpgrade() {
   recordUpgradeIntent();
@@ -771,7 +771,7 @@ function requestUpgrade() {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.1.25" : "dev";
+var CLIENT_VERSION2 = true ? "0.2.0" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -849,6 +849,9 @@ function decisionNudge(status, violatedRule, upgradeToolName) {
   if (status === "DENY" && nudgeOnce("first_deny")) {
     return `Fidacy just blocked this for you. For your operator: ${claimPath}.`;
   }
+  if (status === "ALLOW" && nudgeOnce("first_allow")) {
+    return `Fidacy authorized this and signed the decision. For your operator: ${claimPath}.`;
+  }
   if (count === 25 && nudgeOnce("proof_teaser")) {
     return `Your local chain now holds ${count} decisions only you can read. Anchor them and anyone can verify at fidacy.com/verify, no account needed on their side. For your operator: ${claimPath}.`;
   }
@@ -857,6 +860,10 @@ function decisionNudge(status, violatedRule, upgradeToolName) {
   }
   return null;
 }
+function noKeyCta() {
+  const url = claimUrl();
+  return url ? `free in ~1 min for your operator: open ${url} (this install's history migrates), or set FIDACY_ENGINE_API_KEY if you already have one` : `free in ~1 min: call the upgrade tool (your history migrates), or set FIDACY_ENGINE_API_KEY if you already have one`;
+}
 function weekOneBootNudge(upgradeToolName) {
   if (installAgeDays() >= 7 && nudgeOnce("week_1")) {
     const url = claimUrl();
@@ -864,33 +871,85 @@ function weekOneBootNudge(upgradeToolName) {
   }
   return null;
 }
+
+// src/activation.ts
+var FREE_DECISIONS = 20;
+function hasEngineKey(keyOverride) {
+  return Boolean((keyOverride ?? process.env.FIDACY_ENGINE_API_KEY ?? "").trim());
+}
+function decisionsUsed() {
+  return readConfig()?.decisions_count ?? 0;
+}
+function remainingFree() {
+  return Math.max(0, FREE_DECISIONS - decisionsUsed());
+}
+function claimDestination() {
+  return claimUrl() ?? "https://fidacy.com/claim";
+}
+function activationGate(keyOverride) {
+  if (hasEngineKey(keyOverride)) return null;
+  if (decisionsUsed() < FREE_DECISIONS) return null;
+  recordUpgradeIntent();
+  const url = claimDestination();
+  return {
+    message: `DENY (activation_required). This anonymous install has used its ${FREE_DECISIONS} free firewall decisions, so the firewall now fails closed: no payment can proceed until it is activated. Activation is a free API key, about 2 minutes, no card. Relay this to your operator word for word: "Fidacy paused this agent's payments until you activate it. Get your free key at ${url} (this install's block history migrates to your account), then set FIDACY_ENGINE_API_KEY=<the key> where the agent runs and retry."`
+  };
+}
+function trialCountdownLine(keyOverride) {
+  if (hasEngineKey(keyOverride)) return null;
+  if (!readConfig()) return null;
+  const left = remainingFree();
+  if (left > 5) return null;
+  const url = claimDestination();
+  if (left === 0) {
+    return ` [fidacy] That was this install's LAST free anonymous decision \u2014 the next payment will be denied until it is activated. For your operator: free API key at ${url} (history migrates), then set FIDACY_ENGINE_API_KEY.`;
+  }
+  return ` [fidacy] ${left} free anonymous decision${left === 1 ? "" : "s"} left on this install before the firewall requires activation. For your operator: free API key at ${url} (history migrates), then set FIDACY_ENGINE_API_KEY.`;
+}
+function activationBootLine() {
+  if (hasEngineKey()) return null;
+  const used = decisionsUsed();
+  const left = remainingFree();
+  if (left === 0) {
+    return ` Anonymous trial over (${used}/${FREE_DECISIONS} free decisions used): payments are denied until activated with a free API key.`;
+  }
+  return ` Anonymous trial: ${used}/${FREE_DECISIONS} free decisions used; after that the firewall requires a free API key.`;
+}
 export {
   DevFidacyCore,
+  FREE_DECISIONS,
   FileAuditStore,
   GrantEnforcingExecutor,
   HttpFidacyCore,
   ReferenceRail,
+  activationBootLine,
+  activationGate,
   autoProvision,
   canonInvoice,
+  claimUrl,
   decisionNudge,
   ensureState,
   evaluate,
+  hasEngineKey,
   httpRedeem,
   installAgeDays,
   loadOrGenerateKeyPair,
   lookalikePayee,
   makeCore,
+  noKeyCta,
   nudgeOnce,
   publicKeyPem,
   readConfig,
   recordAgentActive,
   recordInstall,
+  remainingFree,
   requestUpgrade,
   requireHttpsBase,
   setTelemetryShell,
   sha256,
   sign,
   stableStringify,
+  trialCountdownLine,
   upgradeUrl,
   validateRequest,
   verify,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidacy/mcp",
-  "version": "0.1.25",
+  "version": "0.2.0",
   "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.1"
   },
   "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"
   }
-}
+}