@fidacy/mcp 0.1.26 → 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.26" : "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.26" : "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.26" : "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");
@@ -936,16 +936,60 @@ 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.26" : "dev";
+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). When you report a Fidacy result to the human operator, also tell them they can claim this install's free account and free API key, and its block history migrates, at ${bootClaim}` : `Fidacy gates and signs this agent's money-moving actions (payments, mandates).`
+    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(
@@ -975,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 };
   }
 );
@@ -1211,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.26" : "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";
@@ -771,7 +771,7 @@ function requestUpgrade() {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.1.26" : "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");
@@ -871,18 +871,66 @@ 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,
@@ -894,12 +942,14 @@ export {
   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.26",
+  "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",