@fidacy/openclaw-plugin 0.5.7 → 0.5.9

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.5.9
+
+### Patch Changes
+
+- 5090ab4: Closes the two gaps the 0.5.8 scan named: "material disclosure gaps around session logs and outbound anchoring".
+
+  - **Session logs.** 0.5.8 deleted a wrong claim (a `~/.fidacy/sessions/` directory this plugin never creates) without replacing it, which left the loudest question unanswered: the plugin sees the command, path and arguments of every tool call, so where does that go? It is held in memory for the life of the process and never written to disk. What survives is the digest plus per-category counts. The readable session log belongs to the separate MCP-plus-hooks install, which is now named so the difference is explicit.
+  - **Outbound anchoring.** The endpoint was listed but not its trigger, and the trigger is the non-obvious part: when an engine key is set, queued session digests are drained on the first tool call of a LATER session, not at the end of the session that produced them, and nothing asks first. Now stated, along with how to stop it.
+  - A fourth local file, the `pending-anchors.taking` lock, was still undisclosed. The list now names all four.
+
+  Documentation only. Every claim checked against the code: the plugin imports `queuePending`, `sessionLabel`, `sessionSummary` and `takePending` from the shared evidence module, and never `writeSessionLog`.
+
+## 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

package/README.md

@@ -12,19 +12,49 @@ Read this before installing. Since 0.5.0 the plugin is not payment-only: it
 hooks every agent tool call to build a session report, and each session ends in
 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
+**The session log is never written to disk by this plugin.** The plugin sees the
+command, file path and arguments of every tool call, and keeps that record in
+memory for the life of the process only. It is not persisted, not on shutdown,
+not anywhere. What survives a session is the hash digest of that record plus
+per-category counts (for example `shell: 9, file: 4`), and nothing else from it.
+If you want the readable session log on disk, that is the separate MCP-plus-hooks
+install (`npx @fidacy/mcp install-hooks`), which writes `~/.fidacy/sessions/`.
+This plugin does not: it never calls the function that writes them.
+
+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` (directory mode 0700): one line per finished
+  session holding its digest, id, timestamp and per-category counts. No command,
+  path or argument. Lines are removed once anchored.
+- `~/.fidacy/pending-anchors.taking`: a lock file, present only while that queue
+  is being drained
+
+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 and the session digest, plus any hash you
+  anchor with `anchor_artifact`. Hashes and counts only; no file content and no
+  command text. **This one is automatic, so be clear on when it fires:** if an
+  engine key is set, the queued digests are drained on the first tool call of a
+  LATER session, not at the end of the session that produced them. Nobody
+  confirms it. With no engine key nothing is ever sent and the queue simply
+  sits on your disk; delete `~/.fidacy/pending-anchors.jsonl` to discard it.
+- `/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 +133,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 four 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 +181,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

@@ -5102,7 +5102,7 @@ var FileAuditStore = class {
 import { statSync } from "node:fs";
 
 // ../mcp/src/telemetry.ts
-var CLIENT_VERSION = true ? "0.5.7" : "dev";
+var CLIENT_VERSION = true ? "0.5.9" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -5317,7 +5317,7 @@ function requestUpgrade() {
 }
 
 // ../mcp/src/provision.ts
-var CLIENT_VERSION2 = true ? "0.5.7" : "dev";
+var CLIENT_VERSION2 = true ? "0.5.9" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -5460,7 +5460,7 @@ function trialCountdownLine(keyOverride) {
 }
 
 // ../mcp/src/register.ts
-var CLIENT_VERSION3 = true ? "0.5.7" : "dev";
+var CLIENT_VERSION3 = true ? "0.5.9" : "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.7",
+  "version": "0.5.9",
   "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 — 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.7",
+  "version": "0.5.9",
   "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)",