actionfence

# ActionFence — Complete Integration Reference

> ActionFence is an npm package (v0.3.0) that enforces AI agent policies on MCP servers, Express/Fastify APIs, and LangGraph/LangChain tool execution. It uses JSON policy files to control which actions agents can perform, with identity verification (JWT/JWKS), spend caps (per-action, session, daily, and rolling-window), rate limiting, HMAC-signed receipts, pluggable storage backends (SQLite or PostgreSQL), wildcard scope matching, human approval webhook, schema drift checks, conservative policy generation, receipt visibility CLI commands, and simulation mode. Node.js >= 20 required.

## Install

```bash
npm install actionfence
```

For MCP server usage, also install the MCP SDK (optional peer dependency):

```bash
npm install actionfence @modelcontextprotocol/sdk
```

For PostgreSQL storage, also install the pg driver (optional peer dependency):

```bash
npm install actionfence pg
```

## Core Concepts

ActionFence has two main entry points:
- `withGuard(server, options)` — for MCP servers. Monkey-patches `server.registerTool()` to intercept all tool calls.
- `guard(options)` — for Express/Fastify. Returns standard HTTP middleware.
- `withLangChainTools(tools, options)` / `withLangChainTool(tool, options)` — for LangGraph/LangChain tool wrappers.

Both read a `guard-policy.json` file that defines what actions are allowed, identity requirements, spend caps, and rate limits. Every decision (allow or block) is logged as a signed receipt. Receipts are stored in SQLite by default, or PostgreSQL for multi-instance deployments.

## MCP Server Integration

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { withGuard } from 'actionfence';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

// Install ActionFence — one line. Must be called BEFORE registerTool().
const guard = withGuard(server, {
  policy: './guard-policy.json',
  // Optional: enable JWKS verification for verified identity tier
  // identityReaderOptions: {
  //   jwksUri: 'https://issuer.example/.well-known/jwks.json',
  //   issuer: 'https://issuer.example',
  //   audience: 'my-server',
  // },
});

// Register tools normally — ActionFence intercepts automatically
server.registerTool('search', {
  description: 'Search items',
  inputSchema: {
    type: 'object' as const,
    properties: { query: { type: 'string' } },
    required: ['query'],
  },
}, async (params: { query: string }) => {
  return { content: [{ type: 'text' as const, text: `Results for ${params.query}` }] };
});

// Connect transport
const transport = new StdioServerTransport();
await server.connect(transport);
```

## Express/Fastify Integration

```typescript
import express from 'express';
import { guard } from 'actionfence';

const app = express();
app.use(express.json());

// Install ActionFence middleware
const actionfence = guard({
  policy: './guard-policy.json',
  // Map Express routes to policy action names
  actionResolver: (toolName: string) => {
    // toolName is "METHOD /path" e.g. "GET /users" or "POST /orders"
    // Use regex to normalize dynamic segments:
    if (/^GET \/orders\/[^/]+$/.test(toolName)) return 'GET /orders/:id';
    return toolName;
  },
  // Extract spend amount from request body
  spendExtractor: (params: unknown) => {
    const body = (params as { body?: { amount?: number } })?.body;
    return body?.amount ?? null;
  },
});

app.use(actionfence);

// Define routes normally — ActionFence protects all of them
app.get('/items', (_req, res) => { res.json({ items: [] }); });
app.post('/orders', (req, res) => { res.status(201).json({ status: 'created' }); });

app.listen(3000);

// Cleanup on shutdown
process.on('SIGINT', () => { actionfence.dispose(); process.exit(0); });
```

## LangGraph / LangChain Integration

```typescript
import { tool } from '@langchain/core/tools';
import { ToolNode } from '@langchain/langgraph/prebuilt';
import { withLangChainTools } from 'actionfence';
import * as z from 'zod';

const searchOrders = tool(
  async ({ query }: { query: string }) => `Found orders for ${query}`,
  {
    name: 'search_orders',
    description: 'Search orders by query',
    schema: z.object({
      query: z.string(),
    }),
  },
);

const guarded = withLangChainTools([searchOrders], {
  policy: './guard-policy.json',
  contextResolver: ({ config }) => {
    const token = (config as { configurable?: { token?: string } } | undefined)?.configurable
      ?.token;
    return token ? { headers: { authorization: `Bearer ${token}` } } : undefined;
  },
});

const toolNode = new ToolNode(guarded.tools);
```

`withLangChainTools()` shares one `GuardEngine` across the wrapped tools. When
ActionFence blocks a tool, the wrapper throws `ActionFenceToolError`; catch that
in LangChain middleware (`wrapToolCall`) or in a custom LangGraph tool node if
you want to convert it into a framework-native `ToolMessage`.

## Policy File Format (guard-policy.json)

Create with `npx actionfence init` or write manually:

```json
{
  "$schema": "https://raw.githubusercontent.com/saifeldeen911/actionfence/main/schemas/guard-policy.schema.json",
  "service": "MyService",
  "version": "1.0",
  "default_rule": "deny",
  "actions": {
    "search": {
      "allowed": true,
      "identity": "any"
    },
    "create_order": {
      "allowed": true,
      "identity": "verified",
      "max_spend": 500,
      "currency": "USD",
      "requires_human_approval": true
    },
    "delete_all": {
      "allowed": false
    }
  },
  "rate_limits": {
    "requests_per_minute": 30,
    "transactions_per_day": 5
  },
  "spend_limits": {
    "session_max": 1000,
    "daily_max": 2500,
    "window": {
      "max_amount": 500,
      "duration_minutes": 60
    },
    "currency": "USD"
  }
}
```

### Policy fields

- `service` (string, required): Service name.
- `version` (string, required): Policy version identifier.
- `default_rule` ("allow" | "deny", optional): What to do when an action is not listed. Defaults to "deny".
- `actions` (object, required): Map of action name to rule object.
- `rate_limits` (object, optional): `requests_per_minute` and `transactions_per_day`.
- `spend_limits` (object, optional): `session_max`, `daily_max`, `window` (rolling-window cap), and `currency`.
- `schema_enforcement` (object, optional): `on_mismatch` — `"warn"` (default) or `"block"`.
- `regulations` (string[], optional): Parsed as policy metadata but not enforced.

### Rolling-window spend caps

The `spend_limits.window` field adds time-based spend protection. It prevents agents from exhausting budgets through many small transactions ("death by a thousand cuts").

```json
"spend_limits": {
  "session_max": 1000,
  "daily_max": 2500,
  "window": {
    "max_amount": 500,
    "duration_minutes": 60
  },
  "currency": "USD"
}
```

Behavior:
- `max_amount`: Maximum cumulative spend allowed within the rolling window
- `duration_minutes`: Window duration in minutes (sliding, not fixed)
- Entries older than `duration_minutes` are automatically evicted (lazy eviction)
- Window check runs in the same pipeline as session/daily checks — whichever limit triggers first blocks the action
- Fully optional — omitting `window` preserves v0.1 behavior exactly

### Action rule fields

- `allowed` (boolean, required): Whether the action is permitted.
- `identity` ("any" | "token" | "verified", optional): Minimum identity tier. Default "any".
- `max_spend` (number, optional): Per-invocation spend cap in major currency units.
- `currency` (string, optional): ISO 4217 currency code.
- `requires_human_approval` | `boolean` | `false` | When true, pauses evaluation only if `onApprovalRequired` is configured; otherwise the decision records the requirement and proceeds.
- `schema_hash` (string, optional): Pinned SHA-256 hash of the tool's input schema. Set via `actionfence pin-schemas`.
- `schema_snapshot` (object, optional): Pinned copy of the tool input schema used by `actionfence pin-schemas --diff` to produce human-readable field drift.

### Identity tiers

- `anonymous`: No credentials. Lowest tier.
- `token`: Bearer token present but not signature-verified.
- `verified`: JWT verified via JWKS. Highest tier.

The tier hierarchy is: anonymous < token < verified. An action requiring "token" accepts both "token" and "verified".

## GuardOptions Reference

All options for both `withGuard()` and `guard()`:

| Option | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `policy` | `string` | - | Path to guard-policy.json |
| `simulate` | `boolean` | `false` | Dry-run mode |
| `silent` | `boolean` | `false` | Suppress console output |
| `secret` | `string` | - | HMAC signing secret |
| `storage` | `StorageConfig` | `sqlite` | Backend selection |
| `receiptFailureMode` | `'allow' \| 'block'` | `'allow'` | Use `'block'` to fail closed when receipt persistence fails |
| `identityReaderOptions` | `object` | - | JWKS settings |
| `actionResolver` | `(toolName, params) => string` | - | Map tools/routes to policy keys |
| `spendExtractor` | `(params) => number` | - | Extract spend from params |
| `transactionResolver` | `(toolName, params, decision) => boolean` | - | Override transaction classification |
| `onDecision` | `(decision) => void` | - | Metrics, logging, hooks |
| `onApprovalRequired` | `(decision) => Promise<boolean>` | - | Webhook callback to pause and await human approval |
| `approvalTimeoutMs` | `number` | `30000` | Timeout for approval in milliseconds |
| `watchPolicy` | `boolean` | `false` | Hot-reload file-backed policies |
| `payloadRedactor` | `(params) => unknown` | - | Redact sensitive fields |
| `maxPayloadBytes` | `number` | `65536` | Max stored payload size |

## Storage Backends

ActionFence v0.2.0 introduces a pluggable storage adapter layer. Receipt storage defaults to SQLite (zero-config) but can be switched to PostgreSQL for horizontally-scaled deployments.

### SQLite (default)

No configuration needed — SQLite is used automatically. Receipts are stored in `.actionfence/receipts.db`.

```typescript
// Explicit SQLite configuration (equivalent to the default):
withGuard(server, {
  policy: './guard-policy.json',
  storage: {
    adapter: 'sqlite',
    connectionString: './custom-path/receipts.db',  // optional
  },
});
```

### PostgreSQL

For multi-instance deployments where all instances must share a single receipt chain:

1. Install the `pg` driver (optional peer dependency):
   ```bash
   npm install pg
   ```

2. Configure storage:
   ```typescript
   withGuard(server, {
     policy: './guard-policy.json',
     storage: {
       adapter: 'postgres',
       connectionString: process.env.DATABASE_URL,
     },
   });
   ```

3. ActionFence auto-creates the `actionfence_receipts` table and indexes on first use.

### StorageConfig type

```typescript
// SQLite storage configuration
interface SqliteStorageConfig {
  adapter: 'sqlite';
  connectionString?: string;  // optional custom DB file path
}

// PostgreSQL storage configuration
interface PostgresStorageConfig {
  adapter: 'postgres';
  connectionString: string;   // required — pg connection string
  poolConfig?: PoolConfig;    // optional — raw pg.Pool config overrides
}

type StorageConfig = SqliteStorageConfig | PostgresStorageConfig;
```

### Custom Storage Adapters

For advanced use cases, implement the `StorageAdapter` interface and pass it via `receiptStore`:

```typescript
import { ReceiptStore, type StorageAdapter } from 'actionfence';

class MyCustomAdapter implements StorageAdapter {
  insert(receipt) { /* ... */ }
  getLastHash() { /* ... */ }
  getById(id) { /* ... */ }
  listByAgent(agentId) { /* ... */ }
  count(filters?) { /* ... */ }
  query(filters?, limit?) { /* ... */ }
  getAllOrdered() { /* ... */ }
  close() { /* ... */ }
}

const store = new ReceiptStore({ adapter: new MyCustomAdapter() });

withGuard(server, {
  policy: './guard-policy.json',
  receiptStore: store,
});
```

### StorageAdapter Interface

All adapter methods may return `T` or `Promise<T>`:

```typescript
interface StorageAdapter {
  insert(receipt: ActionReceipt): void | Promise<void>;
  getLastHash(): string | Promise<string>;
  getById(receiptId: string): ActionReceipt | null | Promise<ActionReceipt | null>;
  listByAgent(agentId: string): readonly ActionReceipt[] | Promise<readonly ActionReceipt[]>;
  count(filters?: ReceiptFilters): number | Promise<number>;
  query(filters?: ReceiptFilters, limit?: number): readonly ActionReceipt[] | Promise<readonly ActionReceipt[]>;
  getAllOrdered(): readonly ActionReceipt[] | Promise<readonly ActionReceipt[]>;
  close(): void | Promise<void>;
}
```

### ReceiptFilters

```typescript
interface ReceiptFilters {
  agentId?: string;     // filter by agent ID
  action?: string;      // filter by action name
  status?: 'PASSED' | 'BLOCKED';  // filter by decision status
  since?: Date;         // receipts from this timestamp onward
  until?: Date;         // receipts up to this timestamp
}
```

### Built-in Adapters

ActionFence ships with three adapters:

- `SQLiteAdapter` — default, file-based, zero-config. Uses `better-sqlite3`.
- `PostgresAdapter` — async, connection-pooled via `pg.Pool`. Requires `npm install pg`.
- `MemoryAdapter` — in-memory, no persistence. Useful for tests.

```typescript
import { SQLiteAdapter, PostgresAdapter, MemoryAdapter } from 'actionfence';
```

## CLI

```bash
npx actionfence init                                    # Create starter guard-policy.json
npx actionfence init --service MyAPI                    # With custom service name
npx actionfence init --output ./policies/policy.json    # Custom output path
npx actionfence generate "node server.js" --output guard-policy.json --pin-schemas  # Discover tools and generate a blocked review policy
npx actionfence validate guard-policy.json              # Validate policy against JSON Schema
npx actionfence validate guard-policy.json "node server.js"  # Also check schema drift
npx actionfence pin-schemas guard-policy.json "node server.js"  # Pin tool schema hashes
npx actionfence pin-schemas guard-policy.json "node server.js" --diff  # Read-only schema drift review, exits 2 on drift
npx actionfence simulate guard-policy.json --action search         # Dry-run as anonymous
npx actionfence simulate guard-policy.json --action create_order --identity verified --spend 250
npx actionfence receipts list --db .actionfence/receipts.db --status BLOCKED
npx actionfence receipts verify --db .actionfence/receipts.db --key .actionfence/key
npx actionfence receipts export --db .actionfence/receipts.db --format csv --output receipts.csv
```

## Simulation Mode

Runs the full policy pipeline without executing the handler or storing a receipt.

MCP: `withGuard(server, { policy: './guard-policy.json', simulate: true })`
Express: `guard({ policy: './guard-policy.json', simulate: true })`
Per-request (Express): Send `X-ActionFence-Simulation: true` header.

## Receipts

In normal operation, every enforced decision stores a signed receipt. Receipts are HMAC-SHA256 signed, hash-chained, and append-only. The storage backend is determined by `options.storage`:

- **SQLite (default):** `.actionfence/receipts.db` — single-instance, zero-config.
- **PostgreSQL:** `actionfence_receipts` table — multi-instance, horizontally-scaled.

Receipt persistence defaults to backward-compatible allow mode: failures are logged and successful policy decisions can return `receipt: null`. Set `receiptFailureMode: 'block'` to return `ACTIONFENCE_RECEIPT_PERSISTENCE_FAILED` (HTTP 503 for Express or an MCP error result) and prevent handler execution when receipt storage is unavailable. Simulation mode never writes receipts.

Operator CLI:
- `actionfence receipts list` prints filtered receipt rows from SQLite or PostgreSQL storage
- `actionfence receipts verify` checks the stored hash chain and signatures
- `actionfence receipts export --format json|csv` writes filtered evidence to stdout or a file
- `verify` must use the original signing material via `--secret`, `--key`, `ACTIONFENCE_SECRET`, or `AGENTGUARD_SECRET`

Signing key resolution order:
1. `options.secret`
2. `ACTIONFENCE_SECRET` environment variable
3. Auto-generated `.actionfence/key` file

## Trust Model

ActionFence runs on **your server** as middleware. The agent communicates
with your server via MCP protocol or HTTP — it never has direct access
to the policy file or the enforcement engine.

This is server-side enforcement, not a client-side honor system.

- The agent **cannot** read `guard-policy.json` — it's a file on your server
- Tool calls routed through ActionFence are evaluated before they reach your real handlers
- The agent **cannot** tamper with receipts — they're signed with your secret key

> **Tip:** Keep `guard-policy.json` outside any tool-accessible directories.
> If your MCP server has a `read_file` tool, make sure it can't access
> the directory where your policy file lives.

ActionFence only enforces actions that pass through the protected MCP or HTTP boundary. It does not replace branch protection, deploy approvals, scoped cloud tokens, scoped GitHub App permissions, or other infrastructure-level controls.

### Payload Requirements

- `params` must be JSON-serializable.
- Unsupported values such as `BigInt`, `Symbols`, and circular references fail before receipt creation.
- `undefined` values are omitted by canonicalization, and `NaN` or `Infinity` become `null`.
- If you configure `payloadRedactor`, return a sanitized copy and avoid mutating the input.
- Payloads larger than `maxPayloadBytes` are replaced with a truncation marker in the stored receipt.
- Receipts bind both the original request hash and the stored payload-view hash.

## Tool Schema Drift Detection

ActionFence can detect when an MCP server's tool schemas change after you've pinned them. This catches silent breaking changes that could cause agent failures or enable payload injection.

### Generating Starter Policies

```bash
actionfence generate "node server.js" --output guard-policy.json --pin-schemas
actionfence validate guard-policy.json "node server.js"
```

`actionfence generate` connects to the MCP server, discovers tools, and writes a valid starter `guard-policy.json`. The generated policy uses `default_rule: "deny"` by default, writes each discovered tool as an action with `allowed: false`, refuses to overwrite an existing output file, and only includes `schema_hash` values when `--pin-schemas` is passed. Treat the output as a review starting point, not a completed security review.
When `--pin-schemas` is used, generated actions also include a `schema_snapshot` so later drift reviews can show field-level changes instead of only hash mismatches.

### Pinning Schemas

```bash
actionfence pin-schemas guard-policy.json "node server.js"
```

Connects to the MCP server, fetches all tools, computes SHA-256 hashes of each tool's `inputSchema`, and writes the hashes into the policy file under each action's `schema_hash` field.

### Reviewing Drift Without Rewriting

```bash
actionfence pin-schemas guard-policy.json "node server.js" --diff
```

`--diff` is read-only. It compares live MCP tool schemas against the pinned policy snapshot, prints added fields, removed fields, type changes, enum changes, and required-field changes, and returns exit code `2` when drift is found so CI can fail usefully. Policies pinned before `schema_snapshot` support was added still report drift, but detailed field-level output is unavailable until they are repinned once.

### Validating for Drift

```bash
actionfence validate guard-policy.json "node server.js"
```

Compares live tool schemas against pinned hashes and reports any mismatches.

### Runtime Enforcement

Configure `schema_enforcement` in your policy:

```json
{
  "schema_enforcement": {
    "on_mismatch": "warn"
  }
}
```

| `on_mismatch` | Behavior                                                                 |
| ------------- | ------------------------------------------------------------------------ |
| `"warn"`      | Logs a warning on drift but allows the action (default if not configured) |
| `"block"`     | Blocks the action if the schema has drifted from the pinned hash          |

When `schema_enforcement` is omitted, pinned schema hashes are still checked with warning behavior. Set `on_mismatch` to `"block"` to deny drifted tools at runtime.

## Scope Enforcement

If a verified JWT includes a `capabilities` claim (string array), ActionFence treats it as an allowlist. A request passing policy checks but not listed in `capabilities` is blocked.

## v0.2.0 Changes from v0.1

- Receipt storage is now pluggable via `StorageAdapter` interface (SQLite, PostgreSQL, Memory, or custom)
- New `storage` option in `GuardOptions` for declarative backend selection
- All `ReceiptStore` methods are now async (`Promise<T>`)
- New `count()` and `query()` methods with `ReceiptFilters` for receipt introspection
- `AsyncMutex` protects hash-chain integrity during concurrent inserts
- `pg` is an optional peer dependency (`npm install pg` only when using Postgres storage)
- `GuardEngine` uses lazy async initialization — `withGuard()` and `guard()` remain synchronous
- **Rolling-window spend caps** via `spend_limits.window` with `max_amount` and `duration_minutes`
- New `SpendTracker.checkWindow()` for rolling-window enforcement with lazy eviction
- `SpendSnapshot` now includes optional `windowTotal` and `windowResetMs` fields
- **Global circuit breaker** via `circuit_breaker` policy field to halt all agent activity if total spend exceeds a threshold
- **Limit introspection API** via `guardInstance.getAgentStatus(agentId)` to query agent limits passively
- **Wildcard scope matching** for policy action names using prefix wildcards (e.g., `book_*`)
- **Human approval webhook** via `onApprovalRequired` callback in `GuardOptions` to pause requests and await async approval
- **Tool schema drift detection** via `schema_hash` action field and `schema_enforcement` policy field. CLI commands `pin-schemas` and `validate` support live server schema verification.

### Security hardening in v0.2.0

- HMAC signing secrets must be ≥16 bytes (128 bits); shorter keys are rejected at startup
- `payloadRedactor` option strips sensitive fields from receipts; `maxPayloadBytes` (default 64 KB) truncates oversized payloads
- Postgres receipt inserts use advisory-lock transactions to prevent hash-chain fork under concurrent writers
- Policy file paths that resolve outside `process.cwd()` are rejected (path traversal guard)
- JWT `sub` and `owner`/`azp` claims are sanitized: control characters stripped, length capped at 256
- In default allow mode, spend is committed before receipt insertion so spend caps remain conservative if receipt persistence fails; in `receiptFailureMode: 'block'`, spend is committed only after the receipt is stored
- `receiptFailureMode: 'block'` can fail closed when receipt persistence fails, returning `ACTIONFENCE_RECEIPT_PERSISTENCE_FAILED`
- Map size caps and periodic eviction for SpendTracker, RateLimiter, and engine mutexes prevent unbounded memory growth
- `engine.dispose()` closes any Postgres adapter the engine created
- Postgres connection errors mask passwords in connection strings
- Legacy key migration forces 0o600 file permissions

## Current Limitations

- Capability checks are exact string matches only
- No APoP / LAS-WG adapters yet
- LangGraph / LangChain blocked tool calls throw `ActionFenceToolError` by default; convert them into a `ToolMessage` in middleware or a custom tool node if you want model-visible error output
- No path-policy DSL
- `requires_human_approval` can now pause requests if `onApprovalRequired` is configured, though there is no built-in UI
- Receipt persistence fail-closed behavior is opt-in via `receiptFailureMode: 'block'`; default allow mode can still return `receipt: null`
- Money is major-unit only; mixed-currency accounting is out of scope for one policy
- SQLite receipt store is single-instance only (use PostgreSQL for multi-instance)

## Common Integration Patterns

### Express: action names map to "METHOD /path"
The guard middleware constructs the tool name as `METHOD /path` (e.g., `GET /flights`, `POST /bookings`). Use `actionResolver` to normalize dynamic segments:

```typescript
actionResolver: (toolName) => {
  if (/^GET \/users\/[^/]+$/.test(toolName)) return 'GET /users/:id';
  if (/^DELETE \/users\/[^/]+$/.test(toolName)) return 'DELETE /users/:id';
  return toolName;
}
```

### MCP: tool names map directly to action names
For MCP servers, the tool name registered with `server.registerTool('tool_name', ...)` is used as the action name by default. The `actionResolver` is optional and only needed if you want to alias tools.

### LangGraph / LangChain: pass runtime auth through `contextResolver`
Wrapped tools use the tool name as the policy action by default. If your
LangGraph runtime stores auth or agent metadata in `config.configurable` or
similar runtime fields, translate that into ActionFence `RequestContext`:

```typescript
const guarded = withLangChainTools(tools, {
  policy: './guard-policy.json',
  contextResolver: ({ config }) => {
    const token = (config as { configurable?: { token?: string } } | undefined)?.configurable
      ?.token;
    return token ? { headers: { authorization: `Bearer ${token}` } } : undefined;
  },
});
```

### PostgreSQL with Express

```typescript
import express from 'express';
import { guard } from 'actionfence';

const app = express();
app.use(express.json());

const actionfence = guard({
  policy: './guard-policy.json',
  storage: {
    adapter: 'postgres',
    connectionString: process.env.DATABASE_URL,
  },
});

app.use(actionfence);
app.listen(3000);

process.on('SIGINT', () => { actionfence.dispose(); process.exit(0); });
```

### Cleanup
Always call `dispose()` on shutdown to close the database connection:

```typescript
// MCP
const guard = withGuard(server, options);
process.on('SIGINT', () => { guard.dispose(); process.exit(0); });

// Express
const middleware = guard(options);
process.on('SIGINT', () => { middleware.dispose(); process.exit(0); });
```

## Package Exports

```typescript
// Primary — what most users need:
import { withGuard } from 'actionfence';  // MCP middleware
import { guard } from 'actionfence';      // Express middleware
import { withLangChainTools } from 'actionfence'; // LangGraph/LangChain wrappers
import { withLangChainTool } from 'actionfence';  // Single-tool LangGraph/LangChain wrapper
import { ActionFenceToolError } from 'actionfence'; // Tool-call block handling

// Storage adapters:
import { SQLiteAdapter } from 'actionfence';    // Default SQLite backend
import { PostgresAdapter } from 'actionfence';  // PostgreSQL backend
import { MemoryAdapter } from 'actionfence';    // In-memory backend (tests)

// Core modules — for advanced/custom usage:
import { loadPolicy, watchPolicy } from 'actionfence';
import { PolicyEvaluator } from 'actionfence';
import { IdentityReader } from 'actionfence';
import { RateLimiter } from 'actionfence';
import { ReceiptSigner } from 'actionfence';
import { ReceiptStore } from 'actionfence';
import { SpendTracker } from 'actionfence';
import { GuardEngine } from 'actionfence';

// Types:
import type {
  GuardOptions, GuardPolicy, ActionRule, AgentIdentity,
  EvaluationDecision, ActionReceipt, StorageAdapter,
  ReceiptFilters, StorageConfig,
} from 'actionfence';
```

## File Structure After Integration

After installing and configuring ActionFence, your project will have:

```
your-project/
├── guard-policy.json        # Created by `npx actionfence init` or manually
├── .actionfence/            # Auto-created at runtime (add to .gitignore)
│   ├── receipts.db          # SQLite receipt store (when using default storage)
│   └── key                  # Auto-generated HMAC signing key
├── package.json             # actionfence in dependencies
└── src/
    └── index.ts             # Your server with withGuard() or guard()
```

Add `.actionfence/` to your `.gitignore`.

When using PostgreSQL storage, receipts are stored in the `actionfence_receipts` table in your database instead of the local SQLite file.