actionfence

# ActionFence

> ActionFence is a Node.js npm package that acts as an embeddable AI action firewall for MCP servers, Express/Fastify APIs, and LangGraph/LangChain tool execution. It enforces JSON-based policies with identity verification, spend caps (per-action, session, daily, and rolling-window), rate limiting, signed receipts, pluggable storage (SQLite or PostgreSQL), limit introspection API, wildcard scope matching, human approval webhook, tool schema drift detection, and simulation mode. Install with `npm install actionfence`. Requires Node.js >= 20.

- ActionFence uses `withGuard(server, options)` for MCP servers and `guard(options)` for Express middleware
- ActionFence uses `withLangChainTools(tools, options)` or `withLangChainTool(tool, options)` for LangGraph/LangChain tool wrappers; blocked tool calls throw `ActionFenceToolError` unless you convert them to a framework-native tool message
- Policy rules are defined in a `guard-policy.json` file with JSON Schema validation and support for wildcard prefix matching (e.g., `action_*`)
- CLI can generate a conservative starter policy from an MCP server: `npx actionfence generate "node server.js" --output guard-policy.json --pin-schemas`. Generated actions are blocked with `allowed: false` and must be reviewed before use.
- CLI can review schema drift without rewriting the policy: `npx actionfence pin-schemas guard-policy.json "node server.js" --diff`. This read-only mode prints field-level changes and returns exit code `2` when drift is found.
- CLI can inspect stored receipts directly: `npx actionfence receipts list`, `npx actionfence receipts verify`, and `npx actionfence receipts export --format json|csv`. Verification requires the original signing secret (`--secret`, `--key`, or `ACTIONFENCE_SECRET`).
- The package supports ESM and CJS dual-format output
- `@modelcontextprotocol/sdk` is an optional peer dependency (only needed for MCP usage)
- `pg` is an optional peer dependency (only needed for PostgreSQL storage)
- Receipts default to SQLite; set `storage: { adapter: 'postgres', connectionString: '...' }` for horizontally-scaled deployments
- Receipt persistence failures default to backward-compatible allow mode (`receipt: null`); set `receiptFailureMode: 'block'` to return `ACTIONFENCE_RECEIPT_PERSISTENCE_FAILED` and prevent handler execution when storage is unavailable
- Security: HMAC signing secrets must be ≥16 bytes; `payloadRedactor` strips sensitive fields before receipt storage; `maxPayloadBytes` (default 64 KB) truncates oversized payloads
- Trust Model: ActionFence is server-side middleware. Requests routed through ActionFence are evaluated before they reach real handlers. Agents cannot read the policy file or tamper with receipts. Keep guard-policy.json outside tool-accessible directories. ActionFence does not replace branch protection, deploy approvals, or scoped infrastructure tokens.
- Tool params must be JSON-serializable (BigInt, Symbols, circular refs will throw)

## Docs

- [Full LLM integration guide](https://raw.githubusercontent.com/saifeldeen911/actionfence/main/llms-full.txt): Complete self-contained reference with install, setup, API, policy format, storage backends, and working examples for both MCP and Express
- [README](https://raw.githubusercontent.com/saifeldeen911/actionfence/main/README.md): Project overview, quick start, and full API reference
- [Policy JSON Schema](https://raw.githubusercontent.com/saifeldeen911/actionfence/main/schemas/guard-policy.schema.json): Machine-readable schema for guard-policy.json validation
- [CHANGELOG](https://raw.githubusercontent.com/saifeldeen911/actionfence/main/CHANGELOG.md): Version history and release notes

## Examples

- [MCP server example](https://raw.githubusercontent.com/saifeldeen911/actionfence/main/examples/mcp-server/src/index.ts): Flight booking MCP server protected by ActionFence
- [Express API example](https://raw.githubusercontent.com/saifeldeen911/actionfence/main/examples/express-api/src/index.ts): REST API with route-based ActionFence policy
- [LangGraph / LangChain example](https://raw.githubusercontent.com/saifeldeen911/actionfence/main/examples/langgraph-agent/src/index.ts): Wrapped tools for a LangGraph-style tool execution loop
- [Receipt CLI example](https://raw.githubusercontent.com/saifeldeen911/actionfence/main/examples/receipts-cli/README.md): Inspect, verify, and export signed receipts after running a protected server
- [MCP policy file](https://raw.githubusercontent.com/saifeldeen911/actionfence/main/examples/mcp-server/guard-policy.json): Example guard-policy.json for MCP
- [Express policy file](https://raw.githubusercontent.com/saifeldeen911/actionfence/main/examples/express-api/guard-policy.json): Example guard-policy.json for Express
- [LangGraph policy file](https://raw.githubusercontent.com/saifeldeen911/actionfence/main/examples/langgraph-agent/guard-policy.json): Example guard-policy.json for LangGraph / LangChain tools

## Optional

- [Contributing guide](https://raw.githubusercontent.com/saifeldeen911/actionfence/main/CONTRIBUTING.md): Development setup, code style, and PR process
- [Security policy](https://raw.githubusercontent.com/saifeldeen911/actionfence/main/SECURITY.md): How to report vulnerabilities