@fidacy/openclaw-plugin 0.4.0 → 0.4.1

package/README.md

@@ -94,6 +94,41 @@ This is a payment-control plugin, so audit it like one. What it actually does:
   JWKS at `api.fidacy.com/.well-known/jwks.json` with the open-source
   [`@fidacy/verify`](https://www.npmjs.com/package/@fidacy/verify).
 
+## Security
+
+This plugin sits in front of money-moving tool calls, so it should be precise about
+what it touches.
+
+**What it reads.** Your engine credential, from the plugin config field `engineApiKey`
+or from `FIDACY_ENGINE_API_KEY`. Optionally `FIDACY_SIGNING_KEY_B64`, which is your own
+Ed25519 key, so grants are signed with a stable key instead of a per-session one. Both
+belong to you and both are optional. With neither set, the plugin runs the free
+anonymous path and signs with an ephemeral key.
+
+**No credential is embedded.** There is no API key, token, or private key literal in the
+published package, in any version. Check it yourself:
+
+```bash
+cd $(mktemp -d) && curl -sL $(npm view @fidacy/openclaw-plugin dist.tarball) | tar xz && grep -rE "fky_(live|test)_[A-Za-z0-9]{8,}|BEGIN [A-Z ]*PRIVATE KEY" package/ || echo "no credential literals found"
+```
+
+A static scanner may flag the line that resolves your credential as a hardcoded secret,
+because the identifier on the right of the assignment is named like one. It reads your
+config and falls back to the environment, defaulting to the empty string. The command
+above is what settles the question, and the test suite fails the build if a literal ever
+does get in.
+
+**Turning the network off.** `FIDACY_DISABLE_TELEMETRY=1` stops anonymous install and
+usage telemetry. `FIDACY_DISABLE_PROVISION=1` stops the background free-key provisioning.
+With both set and no engine credential, the plugin decides locally and contacts nothing.
+
+**Where the history lives.** Decisions go to a hash-chained log under `~/.fidacy` on your
+machine. That local chain is what makes `spend_summary`, `list_decisions` and
+`get_audit_proof` work with no network. Delete the directory to clear it.
+
+**Files are never uploaded.** `anchor_artifact` and `check_artifact` hash the file locally
+with SHA-256 and send only the 64 hex characters.
+
 ## Prefer MCP instead?
 
 If you'd rather run Fidacy as an MCP server (out-of-process), use

package/dist/index.js

@@ -4739,7 +4739,7 @@ function resolveMandateRules(cfg) {
 }
 
 // ../mcp/src/telemetry.ts
-var CLIENT_VERSION = true ? "0.4.0" : "dev";
+var CLIENT_VERSION = true ? "0.4.1" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -4927,7 +4927,7 @@ function requestUpgrade() {
 }
 
 // ../mcp/src/provision.ts
-var CLIENT_VERSION2 = true ? "0.4.0" : "dev";
+var CLIENT_VERSION2 = true ? "0.4.1" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -5069,7 +5069,7 @@ function trialCountdownLine(keyOverride) {
 }
 
 // ../mcp/src/register.ts
-var CLIENT_VERSION3 = true ? "0.4.0" : "dev";
+var CLIENT_VERSION3 = true ? "0.4.1" : "dev";
 function endpoint3() {
   const base = (process.env.FIDACY_ENGINE_URL ?? "https://api.fidacy.com").replace(/\/$/, "");
   return `${base}/v1/register`;
@@ -5211,7 +5211,7 @@ function renderSummary(s) {
   ];
   if (s.denied > 0) {
     const ranked = Object.entries(s.denied_by_rule).sort((a, b) => b[1] - a[1]);
-    lines.push(`Blocked: ${money(s.blocked_totals)} in attempted value. By rule: ${ranked.map(([rule, n]) => `${rule} (${n})`).join(", ")}.`);
+    lines.push(`Blocked: ${money(s.blocked_totals)} in attempted value. By reason: ${ranked.map(([rule, n]) => `${ruleLabel(rule)} (${n})`).join(", ")}.`);
   }
   if (s.amount_unknown > 0) {
     lines.push(`${s.amount_unknown} record(s) in this window predate amount logging, so the totals above are a floor, not the exact figure.`);
@@ -5238,32 +5238,82 @@ function renderRows(rows) {
   return rows.map((r) => {
     const amount = typeof r.amount === "number" ? `${r.amount.toLocaleString("en-US")} ${r.currency ?? ""}`.trim() : "amount not recorded";
     const who = r.payee ?? "payee not recorded";
-    const why = r.status === "DENY" ? ` blocked by ${r.violatedRule ?? "a rule not recorded on this older entry"}.` : "";
+    const why = r.status === "DENY" ? ` ${explainRule(r.violatedRule, r.payee)}` : "";
     const said = r.purpose ? ` Agent's stated reason: "${r.purpose}".` : "";
     return `#${r.seq} ${r.ts} ${r.status} ${amount} to ${who}.${why}${said} (decision ${r.decisionId})`;
   }).join("\n");
 }
+function ruleLabel(rule) {
+  if (rule.startsWith("payee_lookalike")) return "lookalike payee";
+  if (rule.startsWith("payee_not_in_allowlist")) return "payee not approved";
+  if (rule.startsWith("category_not_allowed")) return "purpose not allowed";
+  if (rule.startsWith("currency_not_allowed")) return "wrong currency";
+  if (rule.startsWith("per_tx") || rule.includes("perTxMax")) return "over the per-payment cap";
+  if (rule.includes("maxTotal") || rule.startsWith("total_cap") || rule.startsWith("budget")) return "over the total budget";
+  if (rule.startsWith("invoice") || rule.includes("duplicate")) return "duplicate invoice";
+  if (rule.startsWith("window") || rule.includes("mandate_window") || rule.includes("expired")) return "outside the mandate window";
+  if (rule.startsWith("revoked") || rule.startsWith("mandate_revoked")) return "mandate revoked";
+  if (rule.startsWith("invalid_mandate")) return "mandate misconfigured";
+  if (rule.startsWith("non_positive_amount")) return "invalid amount";
+  if (rule.startsWith("activation_required")) return "trial used up";
+  if (rule === "not_recorded") return "rule not recorded";
+  return rule;
+}
 function explainRule(rule, payee) {
   if (!rule) return "This entry predates readable rule logging, so the specific rule is not on the record. The decision payload is still covered by the chain digest.";
+  if (rule.startsWith("invalid_mandate")) {
+    const cap = rule.includes("perTxMax") ? "perTxMax" : rule.includes("maxTotal") ? "maxTotal" : null;
+    if (cap)
+      return `The mandate's \`${cap}\` is not a usable number, so the firewall denied rather than run without that cap. Values like "2,500", "$2500" or "2500 USD" all look right to a human and become NaN, and a cap that cannot be compared would silently let everything through. Write it as a bare number: ${cap}: 2500.`;
+    return "The mandate is missing its `allow` block, so there is nothing to enforce and the firewall denied. Check ~/.fidacy/config.json or FIDACY_MANDATE_JSON.";
+  }
+  if (rule.startsWith("payee_lookalike")) {
+    const approved = rule.includes("~") ? rule.split("~")[1] : "an approved payee";
+    return `The payee${payee ? ` "${payee}"` : ""} is a lookalike of your approved payee "${approved}": same name to a human glance, different string. That is the signature of a payee swap, whether from a prompt injection or a spoofed invoice. If it really is a separate vendor, add it to \`payees\` explicitly; if it is not, this attempt is exactly what the firewall exists to stop.`;
+  }
   if (rule.startsWith("payee_not_in_allowlist"))
-    return `The payee${payee ? ` "${payee}"` : ""} is not on the mandate's allowlist. This is the deny-by-default rule doing its job: an agent can only pay counterparties a human put on the list, which is what stops a swapped or lookalike vendor.`;
+    return `The payee${payee ? ` "${payee}"` : ""} is not on the mandate's allowlist. This is the deny-by-default rule doing its job: an agent can only pay counterparties a human put on the list, which is what stops a swapped or lookalike vendor. To authorize this one, add it to \`payees\` in ~/.fidacy/config.json, or pass a full mandate through FIDACY_MANDATE_JSON.`;
   if (rule.startsWith("category_not_allowed"))
-    return "The stated purpose category is not one the mandate permits for this agent.";
+    return "The stated purpose category is not one the mandate permits for this agent. Add it to `categories` in the mandate, or send the payment under a purpose the mandate already allows.";
   if (rule.startsWith("currency_not_allowed"))
-    return "The payment currency is not the mandate's currency.";
+    return "The payment currency is not the mandate's currency. Set `currency` to the one you intend to pay in. A mandate authorizes one currency at a time on purpose, so a swapped currency cannot slip past a cap set in another.";
   if (rule.startsWith("per_tx") || rule.includes("perTxMax"))
-    return "The amount exceeds the per-transaction ceiling in the mandate.";
-  if (rule.includes("maxTotal") || rule.startsWith("budget"))
-    return "The payment would push cumulative spend past the mandate's total budget for the window.";
+    return "The amount exceeds the per-transaction ceiling in the mandate. Raise `perTxMax` if payments this size are expected, or split the payment.";
+  if (rule.includes("maxTotal") || rule.startsWith("budget") || rule.startsWith("total_cap"))
+    return "The payment would push cumulative spend past the mandate's total budget for the window. Raise `maxTotal`, or wait for the window to roll over. Blocked attempts do not consume the budget; only payments that went through do.";
   if (rule.startsWith("invoice") || rule.includes("duplicate"))
-    return "This invoice was already paid once. One payment per invoice is enforced regardless of amount, which is the control that stops a re-presented invoice at a higher figure.";
-  if (rule.startsWith("window") || rule.includes("expired"))
-    return "The mandate was outside its validity window at the moment of the request.";
-  if (rule.startsWith("revoked")) return "The mandate had been revoked.";
+    return "This invoice was already paid once. One payment per invoice is enforced regardless of amount, which is the control that stops a re-presented invoice at a higher figure. If this genuinely is a second, separate payment, give it its own invoiceRef.";
+  if (rule.startsWith("window") || rule.includes("mandate_window") || rule.includes("expired"))
+    return "The mandate was outside its validity window at the moment of the request. Check `notBefore` and `notAfter`, and issue a mandate whose window covers now.";
+  if (rule.startsWith("revoked") || rule.startsWith("mandate_revoked"))
+    return "The mandate had been revoked. A revoked mandate cannot be un-revoked; issue a new one to authorize further payments.";
+  if (rule.startsWith("non_positive_amount"))
+    return "The amount was zero or negative, which is not a payment anyone can authorize. Check what produced that value before retrying.";
   if (rule.startsWith("activation_required"))
     return "The anonymous trial had been used up, so the firewall failed closed. No money can move until the install is activated with a free API key.";
   return `The mandate rule "${rule}" was violated.`;
 }
+function explainEngineError(action, status, type, reasons) {
+  const noun = action === "verdict" ? "assess this action" : action === "anchor" ? "anchor this artifact" : "check this artifact";
+  if (status === 401 || status === 403)
+    return `Fidacy could not ${noun}: the engine rejected the credential (HTTP ${status}). This is not an outage. The key is missing, wrong, or lacks the scope this call needs \u2014 an anonymous provisioned key has no scopes at all. Get an account key at https://fidacy.com/claim and set FIDACY_ENGINE_API_KEY. Nothing was executed.`;
+  if (status === 402)
+    return `Fidacy could not ${noun}: the account is past a spending or quota limit (HTTP 402). The integration is fine; the limit needs settling at https://fidacy.com/claim. Nothing was executed.`;
+  if (status === 429)
+    return `Fidacy could not ${noun}: too many requests in a short window (HTTP 429). Retry in a few seconds. Nothing was executed, and no decision was recorded.`;
+  if (status === 404 && action === "check")
+    return "No anchor exists for that hash on this account. Either the artifact was never anchored, or its contents changed since it was \u2014 if you expected a match, the file is not the one that was anchored.";
+  if (status === 422 || type === "mandate_violation") {
+    const first = reasons?.[0]?.key;
+    const why = first ? ` ${explainRule(first)}` : "";
+    return `Fidacy denied this action: it falls outside the mandate in force.${why} Nothing was executed.`;
+  }
+  if (status >= 500)
+    return `Fidacy could not ${noun}: the engine returned an error (HTTP ${status}). Nothing was executed, and the call was refused rather than allowed through. Retrying is safe.`;
+  if (status === 400)
+    return `Fidacy could not ${noun}: the request was malformed (HTTP 400${type ? `, ${type}` : ""}). This is a bug in how the call was built, not a policy decision. Nothing was executed.`;
+  return `Fidacy could not ${noun} (HTTP ${status}${type ? `, ${type}` : ""}), so the call was refused rather than allowed through. Nothing was executed.`;
+}
 
 // ../mcp/src/sentinel.ts
 var SENTINEL = {
@@ -5537,6 +5587,9 @@ async function findArtifacts(sha2562, cfg) {
 }
 
 // src/index.ts
+function operatorEngineKey(config) {
+  return (config.engineApiKey ?? process.env.FIDACY_ENGINE_API_KEY ?? "").trim();
+}
 var loaded = false;
 function onPluginLoad() {
   if (loaded) return;
@@ -5657,7 +5710,7 @@ ${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}
         async execute(_params, config) {
           const c = boot();
           const mandate = await c.getMandate(subjectOf(config));
-          const hasKey = (config.engineApiKey ?? process.env.FIDACY_ENGINE_API_KEY ?? "").trim().length > 0;
+          const hasKey = operatorEngineKey(config).length > 0;
           const claim = hasKey ? null : claimUrl();
           if (claim) {
             return {
@@ -5697,7 +5750,7 @@ ${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}
         async execute(params, config) {
           const records = await boot().history(5e3);
           const summary = summarize(records, params.days ?? 7);
-          const hasKey = (config.engineApiKey ?? process.env.FIDACY_ENGINE_API_KEY ?? "").trim().length > 0;
+          const hasKey = operatorEngineKey(config).length > 0;
           const claim = hasKey ? null : claimUrl();
           return {
             summary,
@@ -5776,8 +5829,8 @@ ${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}
         async execute(params, config) {
           boot();
           const engineUrl = config.engineUrl ?? process.env.FIDACY_ENGINE_URL ?? "https://api.fidacy.com";
-          const apiKey = (config.engineApiKey ?? process.env.FIDACY_ENGINE_API_KEY ?? "").trim();
-          if (!apiKey) {
+          const engineKey = operatorEngineKey(config);
+          if (!engineKey) {
             throw new Error(
               `assess_action needs an engine key \u2014 ${noKeyCta()}. (Or set plugins.entries.fidacy.config.engineApiKey.)`
             );
@@ -5785,7 +5838,7 @@ ${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}
           try {
             const r = await assessAction(
               { kind: params.kind, mandate: params.mandate, mandateType: params.mandateType, idempotencyKey: params.idempotencyKey, spendingMandate: params.spendingMandate, a2a: params.a2a },
-              { engineUrl, apiKey }
+              { engineUrl, apiKey: engineKey }
             );
             clearHostedLapsed();
             return { summary: `${r.decision} (score ${r.score}) signed by ${r.signingKeyId}`, ...r };
@@ -5795,8 +5848,7 @@ ${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}
                 markHostedLapsed();
                 throw new Error(hostedWallCta("verdict", e.billing));
               }
-              const reasons = e.rejection_reasons?.length ? " (" + e.rejection_reasons.map((x) => x.key).join(",") + ")" : "";
-              throw new Error(`ASSESS ${e.status}: ${e.type}${reasons}`);
+              throw new Error(explainEngineError("verdict", e.status, e.type, e.rejection_reasons));
             }
             throw new Error("ASSESS failed: unexpected error");
           }
@@ -5819,8 +5871,8 @@ ${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}
         async execute(params, config) {
           boot();
           const engineUrl = config.engineUrl ?? process.env.FIDACY_ENGINE_URL ?? "https://api.fidacy.com";
-          const apiKey = (config.engineApiKey ?? process.env.FIDACY_ENGINE_API_KEY ?? "").trim();
-          if (!apiKey) {
+          const engineKey = operatorEngineKey(config);
+          if (!engineKey) {
             throw new Error(
               `anchor_artifact needs an engine key \u2014 ${noKeyCta()}. (Or set plugins.entries.fidacy.config.engineApiKey.)`
             );
@@ -5839,7 +5891,7 @@ ${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}
           try {
             const r = await anchorArtifact(
               { sha256: hash, kind: params.kind ?? "document", ...params.label ? { label: params.label } : {}, ...params.subject ? { subject: params.subject } : {} },
-              { engineUrl, apiKey }
+              { engineUrl, apiKey: engineKey }
             );
             return {
               summary: `ANCHORED ${r.kind} \xB7 sha256 ${hash.slice(0, 16)}\u2026 \xB7 audit seq ${r.audit.seq} \xB7 Bitcoin checkpoint: ${r.anchor.status}. The file never left this machine.`,
@@ -5851,7 +5903,7 @@ ${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}
                 markHostedLapsed();
                 throw new Error(hostedWallCta("anchor", e.billing));
               }
-              throw new Error(`ANCHOR ${e.status}: ${e.type}`);
+              throw new Error(explainEngineError("anchor", e.status, e.type));
             }
             throw new Error("ANCHOR failed: unexpected error");
           }
@@ -5869,8 +5921,8 @@ ${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}
         async execute(params, config) {
           boot();
           const engineUrl = config.engineUrl ?? process.env.FIDACY_ENGINE_URL ?? "https://api.fidacy.com";
-          const apiKey = (config.engineApiKey ?? process.env.FIDACY_ENGINE_API_KEY ?? "").trim();
-          if (!apiKey) {
+          const engineKey = operatorEngineKey(config);
+          if (!engineKey) {
             throw new Error(
               `check_artifact needs an engine key \u2014 ${noKeyCta()}. (Or set plugins.entries.fidacy.config.engineApiKey.)`
             );
@@ -5887,7 +5939,7 @@ ${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}
             }
           }
           try {
-            const r = await findArtifacts(hash, { engineUrl, apiKey });
+            const r = await findArtifacts(hash, { engineUrl, apiKey: engineKey });
             if (!r.artifacts.length) {
               return {
                 summary: `NOT FOUND \xB7 sha256 ${hash.slice(0, 16)}\u2026 has no anchored record in this account. If you expected a match, the file changed since anchoring.`,
@@ -5902,7 +5954,7 @@ ${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}
               ...r
             };
           } catch (e) {
-            if (e instanceof AssessError) throw new Error(`CHECK ${e.status}: ${e.type}`);
+            if (e instanceof AssessError) throw new Error(explainEngineError("check", e.status, e.type));
             throw new Error("CHECK failed: unexpected error");
           }
         }

package/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Fidacy AI Agent Firewall",
   "description": "A signed, independently-verifiable verdict on every money-moving agent action. Blocks wrong/lookalike payee, over-cap, and duplicate-invoice fraud before money moves. Non-custodial, local-first, deny-by-default.",
   "icon": "https://fidacy.com/logo.png",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "contracts": {
     "tools": [
       "request_payment",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidacy/openclaw-plugin",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Fidacy payment firewall as a native OpenClaw plugin: signed, verifiable verdicts on every money-moving agent action, in-process (no MCP subprocess).",
   "license": "Apache-2.0",
   "author": "Fidacy (ZeepCode Group Technology LLC) <hello@fidacy.com> (https://fidacy.com)",
@@ -47,20 +47,21 @@
       "npmSpec": "@fidacy/openclaw-plugin"
     }
   },
+  "scripts": {
+    "build": "node scripts/bundle.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
   "engines": {
     "node": ">=20"
   },
   "devDependencies": {
+    "@fidacy/firewall": "workspace:*",
+    "@fidacy/mcp": "workspace:*",
     "@types/node": "^22.10.0",
     "esbuild": "^0.24.0",
     "openclaw": "2026.6.11",
     "typebox": "1.1.39",
-    "typescript": "^5.6.3",
-    "@fidacy/firewall": "0.1.1",
-    "@fidacy/mcp": "0.5.1"
-  },
-  "scripts": {
-    "build": "node scripts/bundle.mjs",
-    "typecheck": "tsc --noEmit"
+    "typescript": "^5.6.3"
   }
-}
+}