@fidacy/openclaw-plugin 0.5.6 → 0.5.8

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.5.8
+
+### Patch Changes
+
+- 59bd236: Complete and reconcile the privacy disclosure. The ClawHub security audit put this plugin in Review for "inconsistent privacy disclosures about local storage and outbound metadata", and it was right on both counts.
+
+  - **Local storage.** The README claimed local state was `config.json` plus `audit/audit.log` and ended with "Nothing else". `~/.fidacy/pending-anchors.jsonl` was never disclosed. A separate line promised a session log at `~/.fidacy/sessions/`, which belongs to the MCP-plus-hooks install and not to this plugin. Both are now stated once, accurately, as a complete list.
+  - **Outbound metadata.** The README named two network calls. The plugin makes five: `/v1/telemetry`, `/v1/provision`, `/v1/artifacts`, `/v1/assess` and `/v1/register`. All five are now listed with what each one sends and what turns it off, in one place instead of two copies that had drifted apart.
+  - **The static-analysis flag.** `suspicious.env_credential_access` is described accurately now: reading your key and sending it to your engine is what a bearer token is, and every tool that accepts an API key matches that pattern. The old text gave a different and wrong reason ("the identifier is named like a secret"), in a second copy that contradicted the first.
+  - The "verify it yourself" pointer aimed at a mirror repo while releases are provenance-linked to `lucaslubi/fidacy`. It now points where the code actually is, so the instruction works.
+
+  No behaviour changed. This release is documentation only, and every claim in it was checked against the code rather than against the previous README.
+
+## 0.5.7
+
+### Patch Changes
+
+- Four configuration mistakes that presented themselves as security verdicts, so the firewall looked broken and stopped real payments for reasons nobody could see.
+
+  - `FIDACY_MANDATE_JSON` was the last human-authored surface returned verbatim, with no validation of its caps. `"perTxMax": "10000"` built a mandate the engine had to refuse, so **every** payment came back `invalid_mandate_cap:perTxMax=10000` — a message naming 10000 as the invalid cap, when 10000 is a perfectly good number and the quotes were the whole problem. It now honours a quoted number (which means exactly one thing) and refuses anything that would need a guess, loudly, saying that the payees and caps in force are not the ones you wrote.
+  - **Fail-open, now closed:** both window checks are `now < Date.parse(...)` and `now > Date.parse(...)`, and a date that does not parse yields NaN, which makes both comparisons false. An unreadable window was not a narrow window, it was no window: the mandate never expired. An unenforceable window now denies, at the engine as well as at the override.
+  - A quoted cap in `config.json` was discarded silently, so the 2500 default applied and a 5000 payment came back `per_tx_cap_exceeded:5000>2500`, quoting a cap the operator had never set. It now follows the same rule as the environment variables, which had warned since 2026-07-24.
+  - `"currency": "usd"` denied every payment with `currency_not_allowed:USD`, naming as forbidden the exact currency it had allowed. ISO 4217 codes are case-insensitive; case was never a policy decision.
+
+  Nothing was loosened. Caps still cap, a genuinely different currency is still denied, a payee off the allowlist is still denied, and an unreadable value still falls back to the safe default rather than to no limit at all.
+
 ## 0.5.5
 
 ### Patch Changes

package/README.md

@@ -15,16 +15,35 @@ a hash digest anyone can recompute.
 Stays on your machine, always:
 
 - the command, file path and arguments of every tool call
-- the full session log (`~/.fidacy/sessions/`), which is yours to delete
-- your mandate and config (`~/.fidacy/`)
-
-Leaves your machine:
-
-- per-category counts (for example `shell: 9, file: 4`) and the session digest,
-  anchored via the Fidacy engine when the install is activated
-- anonymous telemetry events (install, session, decision counts; a random UUID,
-  never a name or hostname). Disable with `FIDACY_DISABLE_TELEMETRY=1`.
-- your email, only if you set `operatorEmail`, which is opt-in and removable
+- your mandate and config (`~/.fidacy/`), which is yours to delete
+
+Written to disk, and this is the complete list:
+
+- `~/.fidacy/config.json` (mode 0600): the anonymous install id, tier, and your
+  mandate rules
+- `~/.fidacy/audit/audit.log`: the hash-chained decision log
+- `~/.fidacy/pending-anchors.jsonl`: session digests waiting to be anchored,
+  written only while an anchor is queued and cleared once it lands
+
+Leaves your machine, and this is the complete list of hosts and paths. Every one
+goes to your configured engine (`https://api.fidacy.com` by default) and nowhere
+else:
+
+- `/v1/telemetry`: anonymous usage events (install, session, decision counts; a
+  random UUID, never a name or hostname). Off with `FIDACY_DISABLE_TELEMETRY=1`.
+- `/v1/provision`: a background free-key request. Off with
+  `FIDACY_DISABLE_PROVISION=1`.
+- `/v1/artifacts`: per-category counts (for example `shell: 9, file: 4`) and the
+  session digest, plus any hash you anchor with `anchor_artifact`. Hashes and
+  counts only; no file content and no command text.
+- `/v1/assess`: only when you call `assess_action` yourself, and only if you set
+  an engine API key. Sends the action you passed to the tool.
+- `/v1/register`: only if you set `operatorEmail`, which is opt-in and removable.
+  Sends that email and nothing else.
+
+With `FIDACY_DISABLE_TELEMETRY=1`, `FIDACY_DISABLE_PROVISION=1`, no engine key
+and no `operatorEmail`, the plugin makes no network calls at all and gates
+payments entirely offline.
 
 ## The tools
 
@@ -103,22 +122,32 @@ Verify any verdict yourself: https://api.fidacy.com/.well-known/jwks.json
 
 This is a payment-control plugin, so audit it like one. What it actually does:
 
-- **Network calls it makes:** anonymous usage telemetry to `api.fidacy.com/v1/telemetry`
-  (an install UUID plus event enums; never payee, amount, currency, or content) and a
-  background free-key provision to `/v1/provision`. Both are opt-out:
-  `FIDACY_DISABLE_TELEMETRY=1` and `FIDACY_DISABLE_PROVISION=1`. Neither is ever on
-  the decision path; payment gating works fully offline.
-- **Local state:** `~/.fidacy/config.json` (0600; anon id, tier, your mandate rules)
-  and `~/.fidacy/audit/audit.log` (the hash-chained decision log). Nothing else.
+- **Network calls it makes:** the five endpoints listed under "what leaves your
+  machine" above, all on your configured engine and nowhere else. That list is
+  stated once, at the top, on purpose: this section used to carry a second,
+  shorter copy naming only two of them, and a privacy disclosure that
+  contradicts itself is worse than a long one. None of the five is ever on the
+  decision path; payment gating works fully offline.
+- **Local state:** the three files listed above, and nothing else. This bullet
+  used to name two of them and end with "Nothing else", which was not true:
+  `pending-anchors.jsonl` was never disclosed. Delete `~/.fidacy` to clear all
+  of it.
 - **`FIDACY_SIGNING_KEY_B64`:** an OPTIONAL env var the operator sets to pin a
   stable local Ed25519 signing key for grants. If unset, a per-session key is
   generated. The plugin reads it; it never writes or transmits it.
 - **API keys:** read from your plugin config (`engineApiKey`) or the
   `FIDACY_ENGINE_API_KEY` env var, sent only to your configured engine URL
   (default `api.fidacy.com`) as a bearer token. There are no hardcoded keys or
-  secrets in the published bundle; scanner hits on those lines are pattern matches
-  on the env/config reads above, and you can verify yourself: the bundle is
-  unminified on npm and mirrored at github.com/lucaslubi/fidacy-mcp (plugin-native/).
+  secrets in the published bundle. A static analyser will flag this as
+  `suspicious.env_credential_access` ("environment variable access combined with
+  network send"), and that description is accurate: reading your key and sending
+  it to your engine is what a bearer token IS, and every tool that takes an API
+  key matches the same pattern. What the rule cannot tell you is WHOSE key and
+  WHICH host, so check both yourself: the bundle ships unminified, the source is
+  at github.com/lucaslubi/fidacy (`packages/openclaw-plugin`), and every release
+  is provenance-linked to the commit it was built from. The command below settles
+  the "hardcoded secret" question in one line, and the test suite fails the build
+  if a literal ever gets in.
 - **Verify our signatures, not our word:** every verdict checks against the public
   JWKS at `api.fidacy.com/.well-known/jwks.json` with the open-source
   [`@fidacy/verify`](https://www.npmjs.com/package/@fidacy/verify).
@@ -141,15 +170,14 @@ published package, in any version. Check it yourself:
 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.
+On the `suspicious.env_credential_access` finding a static analyser reports here, see
+the "API keys" bullet above. It is stated in one place rather than two, because the
+two copies had drifted into giving different reasons for the same flag.
 
 **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.
+With both set, no engine credential and no `operatorEmail`, the plugin decides locally
+and contacts nothing: those four switches cover all five endpoints listed at the top.
 
 **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

package/dist/index.js

@@ -4320,14 +4320,24 @@ function resolveMandateRules(cfg) {
     }
     return n;
   };
-  const fileNum = (v) => typeof v === "number" && Number.isFinite(v) && v > 0 ? v : void 0;
+  const fileNum = (name, v) => {
+    if (v === void 0 || v === null) return void 0;
+    const n = typeof v === "number" ? v : typeof v === "string" ? Number(v.trim()) : NaN;
+    if (!Number.isFinite(n) || n <= 0) {
+      console.error(
+        `[fidacy] mandate.${name} in config.json is ${JSON.stringify(v)}, which is not a positive number, so it cannot be enforced as a cap. Ignoring it and using the safe default. Write it as a bare JSON number, with no quotes, thousands separator, currency symbol or unit (e.g. "${name}": 2500).`
+      );
+      return void 0;
+    }
+    return n;
+  };
   const payees = envList(process.env.FIDACY_ALLOW_PAYEES) ?? m.payees ?? [];
   return {
     payees: payees.includes(DEMO_PAYEE) ? payees : [...payees, DEMO_PAYEE],
     categories: envList(process.env.FIDACY_ALLOW_CATEGORIES) ?? m.categories ?? ["*"],
     currency: process.env.FIDACY_CURRENCY ?? m.currency ?? "USD",
-    perTxMax: envNum("FIDACY_PER_TX_MAX", process.env.FIDACY_PER_TX_MAX) ?? fileNum(m.perTxMax) ?? 2500,
-    maxTotal: envNum("FIDACY_MAX_TOTAL", process.env.FIDACY_MAX_TOTAL) ?? fileNum(m.maxTotal) ?? 1e4
+    perTxMax: envNum("FIDACY_PER_TX_MAX", process.env.FIDACY_PER_TX_MAX) ?? fileNum("perTxMax", m.perTxMax) ?? 2500,
+    maxTotal: envNum("FIDACY_MAX_TOTAL", process.env.FIDACY_MAX_TOTAL) ?? fileNum("maxTotal", m.maxTotal) ?? 1e4
   };
 }
 
@@ -4759,6 +4769,13 @@ function validateMandateCaps(mandate) {
     return `invalid_mandate_cap:perTxMax=${String(mandate.allow.perTxMax)}`;
   if (bad(mandate.allow.maxTotal))
     return `invalid_mandate_cap:maxTotal=${String(mandate.allow.maxTotal)}`;
+  if (!mandate.window || typeof mandate.window !== "object")
+    return "invalid_mandate:missing_window";
+  for (const campo of ["notBefore", "notAfter"]) {
+    const v = mandate.window[campo];
+    if (typeof v !== "string" || Number.isNaN(Date.parse(v)))
+      return `invalid_mandate_window:${campo}=${String(v)}`;
+  }
   return null;
 }
 function evaluate(mandate, req, spentSoFar) {
@@ -4772,7 +4789,7 @@ function evaluate(mandate, req, spentSoFar) {
     return "before_mandate_window";
   if (now > Date.parse(mandate.window.notAfter))
     return "after_mandate_window";
-  if (req.currency !== mandate.allow.currency)
+  if (req.currency.toUpperCase() !== mandate.allow.currency.toUpperCase())
     return `currency_not_allowed:${req.currency}`;
   if (req.amount <= 0)
     return "non_positive_amount";
@@ -5085,7 +5102,7 @@ var FileAuditStore = class {
 import { statSync } from "node:fs";
 
 // ../mcp/src/telemetry.ts
-var CLIENT_VERSION = true ? "0.5.6" : "dev";
+var CLIENT_VERSION = true ? "0.5.8" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -5193,12 +5210,38 @@ async function flush() {
 }
 
 // ../mcp/src/core.ts
+function normalizaMandatoDeEnv(m) {
+  const allow = m.allow;
+  for (const campo of ["perTxMax", "maxTotal"]) {
+    const v = allow[campo];
+    const n = typeof v === "number" ? v : typeof v === "string" ? Number(v.trim()) : NaN;
+    if (!Number.isFinite(n) || n <= 0) {
+      return `has allow.${campo} = ${JSON.stringify(v)}, which is not a positive number, so that cap cannot be enforced. Write it as a bare JSON number, with no quotes, thousands separator, currency symbol or unit (e.g. "${campo}": 2500).`;
+    }
+    allow[campo] = n;
+  }
+  const window = m.window;
+  for (const campo of ["notBefore", "notAfter"]) {
+    const v = window[campo];
+    if (typeof v !== "string" || Number.isNaN(Date.parse(v))) {
+      return `has window.${campo} = ${JSON.stringify(v)}, which is not a readable date, so the mandate's time window cannot be enforced. Use an ISO 8601 timestamp (e.g. "${campo}": "2026-01-01T00:00:00Z").`;
+    }
+  }
+  return null;
+}
 function buildMandate() {
   if (process.env.FIDACY_MANDATE_JSON) {
     try {
       const parsed = JSON.parse(process.env.FIDACY_MANDATE_JSON);
-      if (parsed && typeof parsed === "object" && parsed.allow && parsed.window) return parsed;
-      console.error("[fidacy] FIDACY_MANDATE_JSON is missing allow/window; ignoring it and using the safe default mandate.");
+      if (parsed && typeof parsed === "object" && parsed.allow && parsed.window) {
+        const problema = normalizaMandatoDeEnv(parsed);
+        if (!problema) return parsed;
+        console.error(
+          `[fidacy] FIDACY_MANDATE_JSON ${problema} The override is being IGNORED and the safe default mandate is in force instead, so your payees and caps are NOT the ones you wrote.`
+        );
+      } else {
+        console.error("[fidacy] FIDACY_MANDATE_JSON is missing allow/window; ignoring it and using the safe default mandate.");
+      }
     } catch (err) {
       console.error(`[fidacy] FIDACY_MANDATE_JSON is not valid JSON (${err.message}); ignoring it and using the safe default mandate.`);
     }
@@ -5274,7 +5317,7 @@ function requestUpgrade() {
 }
 
 // ../mcp/src/provision.ts
-var CLIENT_VERSION2 = true ? "0.5.6" : "dev";
+var CLIENT_VERSION2 = true ? "0.5.8" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -5417,7 +5460,7 @@ function trialCountdownLine(keyOverride) {
 }
 
 // ../mcp/src/register.ts
-var CLIENT_VERSION3 = true ? "0.5.6" : "dev";
+var CLIENT_VERSION3 = true ? "0.5.8" : "dev";
 function endpoint3() {
   const base = (process.env.FIDACY_ENGINE_URL ?? "https://api.fidacy.com").replace(/\/$/, "");
   return `${base}/v1/register`;

package/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Fidacy AI Agent Firewall",
   "description": "Firewall for AI agents. Watches every action the agent takes and ends each session in a digest anyone can recompute; commands, paths and arguments never leave your machine, only counts and a hash. Blocks wrong/lookalike payee, over-cap and duplicate-invoice fraud before money moves. Non-custodial, local-first, deny-by-default. Anonymous telemetry (counts only) can be disabled with FIDACY_DISABLE_TELEMETRY=1.",
   "icon": "https://fidacy.com/logo.png",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "contracts": {
     "tools": [
       "request_payment",
@@ -25,19 +25,19 @@
     "properties": {
       "operatorEmail": {
         "type": "string",
-        "description": "Your email (optional). Ties this agent's protection history to you so it can move into a free account, and lets Fidacy reach you about this install. Never shared; remove any time. Your email (optional) Ties this agent's protection history to you so it can move into a free account, and lets Fidacy reach you about this install. Optional \u2014 the firewall works without it."
+        "description": "Your email (optional). Ties this agent's protection history to you so it can move into a free account, and lets Fidacy reach you about this install. Never shared; remove any time."
       },
       "engineApiKey": {
         "type": "string",
-        "description": "Fidacy engine API key (fky_live_/fky_test_) enabling signed verdicts via assess_action. Falls back to FIDACY_ENGINE_API_KEY. Engine API key Free key at app.fidacy.com/signup. Enables signed trust verdicts (assess_action) and keeps the firewall active past the 20-decision anonymous trial."
+        "description": "Fidacy engine API key (fky_live_/fky_test_) enabling signed verdicts via assess_action. Falls back to FIDACY_ENGINE_API_KEY."
       },
       "engineUrl": {
         "type": "string",
-        "description": "Fidacy engine base URL. Defaults to https://api.fidacy.com (or FIDACY_ENGINE_URL). Engine URL"
+        "description": "Fidacy engine base URL. Defaults to https://api.fidacy.com (or FIDACY_ENGINE_URL)."
       },
       "subject": {
         "type": "string",
-        "description": "Mandate subject identity for this agent. Defaults to agent:demo (or FIDACY_SUBJECT). Agent subject"
+        "description": "Mandate subject identity for this agent. Defaults to agent:demo (or FIDACY_SUBJECT)."
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidacy/openclaw-plugin",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "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)",
@@ -57,7 +57,7 @@
     "typebox": "1.1.39",
     "typescript": "^5.6.3",
     "@fidacy/firewall": "0.1.1",
-    "@fidacy/mcp": "0.7.3"
+    "@fidacy/mcp": "0.7.4"
   },
   "scripts": {
     "build": "node scripts/bundle.mjs",