@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
• 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 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: 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.
• 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/).
• 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"

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