AgentAction
  → Budget check          (cost estimation, daily/monthly caps)
  → Policy evaluation      (OPA/Rego when available, JS fallback otherwise)
  → Validation             (pluggable checkers: semgrep, npm test, checkov, …)
  → Human-in-the-loop      (review for sensitive actions, hash-verified execution)
  → Execution              (injected tool executor)
  → Audit + provenance     (W3C PROV-O records, immutable trail)

npm install
npm run build
npm test            # unit + integration + rego tests
npm run test:e2e    # MCP handler end-to-end tests

node dist/cli/index.js policies              # list built-in rules
node dist/cli/index.js status               # show active evaluator
node dist/cli/index.js evaluate \
  --tool write_file \
  --params '{"path":"prod/secrets.yml"}' \
  --prompt "rotate the password"
# → decision: require_review / deny / allow

Start as a transparent proxy:

```bash
node dist/cli/index.js proxy \
  --backend-command npx \
  -- mcp-server-filesystem /workspace
# → agent connects, every tool/call is intercepted

## Configuration

All configuration is via environment variables (Twelve-Factor). See
`.env.example` for a complete list.

| Variable | Default | Description |
|----------|---------|-------------|
| `LOG_LEVEL` | `info` | Log level: trace, debug, info, warn, error |
| `OPA_POLICY_DIR` | `./policies` | Directory with Rego policy files |
| `OPA_WASM_PATH` | — | Path to pre-built OPA WASM bundle. When set, OPA is the primary evaluator |
| `POLICY_FALLBACK_JS` | `true` | Fall back to TypeScript evaluator when OPA unavailable |
| `DATABASE_URL` | `memory` | PostgreSQL connection string. When unset or `memory`, uses in-memory storage |
| `DEFAULT_DAILY_BUDGET_USD` | `50` | Default per-agent daily budget cap |
| `DEFAULT_MONTHLY_BUDGET_USD` | `1000` | Default per-agent monthly budget cap |
| `HITL_TIMEOUT_SECONDS` | `300` | Review request timeout before auto-deny |
| `GATEWAY_API_KEY` | — | REST API key. **Required** for REST API to function. Without it, all non-healthz routes return 401 |
| `CORS_ORIGIN` | `*` | Allowed CORS origin for REST API |
| `RATE_LIMIT_PER_MINUTE` | `60` | Max actions per agent per minute |
| `MCP_SERVER_NAME` | `agentic-governance-gateway` | MCP server name reported to clients |
| `MCP_SERVER_VERSION` | `0.1.0` | MCP server version |
| `BACKEND_COMMAND` | — | Backend MCP server command (e.g. `npx`). When set, the gateway runs as a transparent proxy |
| `BACKEND_ARGS` | — | JSON array of arguments for the backend command (e.g. `["mcp-server-filesystem","/workspace"]`) |
| `BACKEND_ENV` | — | JSON object of environment variables for the backend process |
| `BACKEND_CWD` | — | Working directory for the backend process (optional) |
| `AGENT_AUTH_ENABLED` | `false` | Enable agent identity verification on MCP `initialize` |
| `AGENT_ALLOWLIST` | — | Comma-separated list of allowed agent IDs (e.g. `claude-code,cursor`) |
| `SHADOW_AGENT_POLICY` | `warn` | Policy for unknown agents: `warn` (log only) or `deny` (block) |
| `DEFAULT_PRIVILEGE_RING` | `1` | Default privilege ring for unauthenticated agents (0=full, 1=sandboxed, 2=read-only) |
| `WORKSPACE_ROOT` | `.` | Root directory for path confinement (Ring 1 agents cannot write outside this) |
| `AGENT_TOOL_ALLOWLIST` | — | Per-agent tool allowlist (format: `agentId:tool1,tool2;agentId2:tool3`) |
| `METRICS_ENABLED` | `true` | Collect Prometheus metrics |
| `METRICS_PORT` | `9090` | Port for the `/metrics` endpoint |
| `DASHBOARD_ENABLED` | `true` | Enable the HTML dashboard at `/dashboard` |

### Production checklist

- [ ] Set `GATEWAY_API_KEY` (generate with `openssl rand -hex 32`)
- [ ] Set `DATABASE_URL` with `?sslmode=require` for TLS
- [ ] Set `CORS_ORIGIN` to your actual origin (not `*`)
- [ ] Place behind a TLS-terminating reverse proxy (nginx, Caddy, Traefik)
- [ ] Configure log aggregation (Pino outputs JSON to stdout)
- [ ] Set up a retention cron for `/admin/purge`

## Connecting an MCP client

`~/.cursor/mcp.json` (Cursor) or the equivalent for Claude Code:

```json
{
  "mcpServers": {
    "agentic-governance-gateway": {
      "command": "node",
      "args": ["/absolute/path/to/dist/mcp/main.js"]
    }
  }
}

┌──────────┐    MCP (stdio)     ┌──────────────────────────────┐
│  Agent   │ ◄─────────────────►│      GATEWAY PROXY           │
│ (Claude) │   tools/list → fwd │                              │
│          │   tools/call →     │  Governance Pipeline         │
│          │     intercept      │  Rate-Limit → Budget →       │
│          │   initialize → fwd │  Policy → Validation → HITL  │
│          │                    │                              │
│          │                    │   allow → forward to backend │
│          │                    │   deny  → MCP error response │
└──────────┘                    └──────────────┬───────────────┘
                                               │ MCP (stdio)
                                               ▼
                                    ┌──────────────────┐
                                    │  Backend MCP     │
                                    │  Server (real)   │
                                    │  filesystem,     │
                                    │  git, bash, ...  │
                                    └──────────────────┘

agentic-gateway proxy \
  --backend-command npx \
  -- mcp-server-filesystem /workspace

BACKEND_COMMAND=npx BACKEND_ARGS='["mcp-server-filesystem","/workspace"]' \
  node dist/proxy/proxy-main.js

// ~/.config/claude-code/mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "agentic-governance-gateway", "proxy",
        "--backend-command", "npx",
        "--", "mcp-server-filesystem", "/workspace"
      ]
    }
  }
}

Tool call denied: Path outside workspace root: /etc/passwd

AGENT_TOOL_ALLOWLIST=claude-code:write_file,read_file,bash;ci-agent:read_file

curl -X POST http://localhost:3000/evaluate \
  -H "content-type: application/json" \
  -H "x-api-key: $GATEWAY_API_KEY" \
  -d '{
    "agentId": "claude-code",
    "sessionId": "s1",
    "tool": "write_file",
    "params": {"path": "prod/secrets.yml"},
    "prompt": "rotate the password"
  }'
# → { "decision": "require_review", "reasons": [...] }

curl -X POST http://localhost:3000/process \
  -H "content-type: application/json" \
  -H "x-api-key: $GATEWAY_API_KEY" \
  -d '{
    "agentId": "claude-code",
    "sessionId": "s1",
    "tool": "write_file",
    "params": {"path": "src/utils.ts"},
    "prompt": "add a helper function"
  }'
# → { "decision": "allow", "audit": { "id": "...", ... } }

# Set the API key first
export GATEWAY_API_KEY=$(openssl rand -hex 32)

docker compose up -d

agentic-governance-gateway/
├── src/
│   ├── core/
│   │   ├── policy-engine/   OPA + JS evaluator, rules
│   │   ├── traceability/    Audit store, PROV-O provenance
│   │   ├── validation/      Pluggable checkers + orchestrator
│   │   ├── hitl/            Human-in-the-loop gateway
│   │   ├── budget/          Cost controller
│   │   ├── gateway.ts        Canonical pipeline façade
│   │   ├── config.ts
│   │   ├── rate-limiter.ts
│   │   └── logger.ts
│   ├── proxy/               Transparent MCP proxy (enforcement mode)
│   ├── identity/            Agent identity + credential store
│   ├── observability/       Prometheus metrics + HTML dashboard
│   ├── mcp/                 MCP server + entrypoint
│   ├── api/                 REST API
│   ├── cli/                 CLI
│   └── types/                Shared TypeScript types
├── policies/                Rego policies + tests
├── tests/
│   ├── unit/                Per-module unit tests
│   ├── integration/         Gateway + parity tests
│   └── e2e/                 MCP handler tests
├── docs/                    Architecture + ADRs
├── examples/                Runnable example policies & configs
├── Dockerfile
├── docker-compose.yml
└── .github/workflows/ci.yml