@fidacy/openclaw-plugin

@fidacy/openclaw-plugin

Fidacy firewall for AI agents as a native OpenClaw plugin: the payment firewall plus a session observer, registered in-process (no MCP subprocess, no npx spawn).

What this plugin observes, and what leaves your machine

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
• 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

• request_payment: authorize a payment against the active signed mandate. ALLOW returns a short-lived Ed25519 grant the executor requires; DENY returns the violated rule and no grant.
• verify_mandate: the active mandate envelope + Fidacy's public key.
• get_audit_proof: tamper-evident, hash-chained proof for any decision.
• assess_action: a SIGNED trust verdict from the live Fidacy engine (requires an engine API key), verifiable by anyone via @fidacy/verify.
• fidacy_upgrade: upgrade the local install to a real Fidacy account.

Plus spend_summary, list_decisions, sentinel_alerts, explain_decision, anchor_artifact and check_artifact.

Same engine as @fidacy/mcp: one engine, many shells. Local-first, deny-by-default, non-custodial: Fidacy authorizes, it never holds funds.

To everyone who installed Fidacy

The Fidacy firewall has taken 3,099 decisions to date, 98% of them blocks, counted by the engine and public at api.fidacy.com/v1/pulse if you want to check the number yourself. Thank you for being part of it. Two things worth a minute of your time:

• 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). Run grep anon_id ~/.fidacy/config.json, then open https://fidacy.com/claim?ref=<that id>. One click turns your local history into a free account with server-signed, Bitcoin-anchored verdicts.

• Founding partner, 5 seats. A full year of the evidence layer at $10,800 instead of $18,000, wired in by the founder, 30-day full refund: fidacy.com/partners

Lucas de Lima, founder

Install (2 minutes)

Step 1: get your free API key at app.fidacy.com/signup (free tier, no card).

Step 2: install and set the key.

openclaw plugins install @fidacy/openclaw-plugin

Plugin config (plugins.entries.fidacy.config):

{
  "engineApiKey": "fky_live_...",
  "engineUrl": "https://api.fidacy.com",
  "subject": "agent:my-agent"
}

engineApiKey enables signed verdicts (assess_action) and keeps the firewall active past the anonymous trial. Environment variables (FIDACY_ENGINE_API_KEY, FIDACY_ENGINE_URL, FIDACY_SUBJECT) are the fallback. Decisions run locally, deny-by-default (deny-unknown-payee + per-tx cap); add trusted payees/caps in ~/.fidacy/config.json.

No key yet? The install works anonymously for its first 20 firewall decisions, then fails closed (payments denied with activation_required) until the free key is set. Claim an anonymous install's history: grep anon_id ~/.fidacy/config.json, then open https://fidacy.com/claim?ref=<that id>.

Verify any verdict yourself: https://api.fidacy.com/.well-known/jwks.json

Security and privacy, point by point

This is a payment-control plugin, so audit it like one. What it actually does:

• 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. 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.

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:

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"

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, 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 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 openclaw mcp add fidacy --command npx --arg -y --arg @fidacy/mcp , same tools, same engine. This plugin is the native, in-process variant.

Build (development)

pnpm --filter @fidacy/openclaw-plugin build      # esbuild → dist/index.js (self-contained)
pnpm --filter @fidacy/openclaw-plugin typecheck  # tsc against the real openclaw plugin-sdk types

openclaw/plugin-sdk/* stays external (the host provides it at runtime); everything else (the shared @fidacy/firewall engine and @fidacy/mcp shell wiring) is inlined so the published package is self-contained.

Apache-2.0 · https://fidacy.com