vizier

<!-- mcp-name: io.github.vassiliylakhonin/vizier-guard -->
# Vizier

**Deterministic Authorization & Non-Repudiation Audit Firewall for AI Agents.**

[![CI](https://github.com/vassiliylakhonin/vizier/actions/workflows/ci.yml/badge.svg)](https://github.com/vassiliylakhonin/vizier/actions/workflows/ci.yml)
[![Deploy](https://github.com/vassiliylakhonin/vizier/actions/workflows/deploy.yml/badge.svg)](https://github.com/vassiliylakhonin/vizier/actions/workflows/deploy.yml)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](packages/python-sdk)
[![npm @vizier/sdk](https://img.shields.io/npm/v/@vizier/sdk.svg)](https://www.npmjs.com/package/@vizier/sdk)
[![npm @vizier/mcp-proxy](https://img.shields.io/npm/v/@vizier/mcp-proxy.svg)](https://www.npmjs.com/package/@vizier/mcp-proxy)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.vassiliylakhonin%2Fvizier-purple.svg)](https://github.com/modelcontextprotocol/registry)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Vizier is an ultra-fast, edge-native deterministic authorization and audit firewall for action-taking AI agents. Before an agent executes an external side effect (making a payment, executing code, modifying a database, dispatching messages, or deploying infrastructure), it submits the proposed action to Vizier.

> ⚡ **Try the Live Interactive Playground**: [https://vizier.vassiliy-lakhonin.workers.dev/playground](https://vizier.vassiliy-lakhonin.workers.dev/playground)  
> Test policy presets (`ALLOW`, `BLOCK_AMOUNT`, `BLOCK_TARGET`, `SENSITIVE`), inspect sub-25ms edge latency, and verify SHA-256 non-repudiation audit receipts in real time directly from your browser.

---

## 🏛️ Architecture

```mermaid
flowchart TD
    subgraph Agents["AI Agent Runtimes"]
        A1["Python Agent (LangChain / CrewAI / AutoGen)"]
        A2["MCP Client (Claude / Cursor / Tools)"]
        A3["TypeScript / Node.js Agent"]
    end

    subgraph Guards["Vizier Enforcement Boundary"]
        G1["@vizier_guard / Python SDK"]
        G2["@vizier/mcp-proxy CLI"]
        G3["@vizier/sdk (TypeScript)"]
    end

    subgraph Kernel["Cloudflare Workers Global Edge"]
        K["Vizier Deterministic Kernel (/v1/verify)"]
        P["Policy Engine: Limits, Targets, Roles, Grants"]
        D1["D1 Audit Ledger & Cryptographic Receipts"]
    end

    subgraph Targets["Protected External Side-Effects"]
        T1["Payment / Financial APIs"]
        T2["Database Writes & Deletions"]
        T3["Worker / Infrastructure Deployments"]
        T4["External Message Dispatch"]
    end

    A1 --> G1
    A2 --> G2
    A3 --> G3

    G1 -->|"POST /v1/verify"| K
    G2 -->|"POST /v1/verify"| K
    G3 -->|"POST /v1/verify"| K

    K --> P
    P --> D1

    G1 -.->|"Decision: ALLOW"| T1
    G2 -.->|"Decision: ALLOW"| T2
    G3 -.->|"Decision: ALLOW"| T3

    P -.->|"Decision: BLOCK / REVIEW"| G1
    P -.->|"Decision: BLOCK / REVIEW"| G2
    P -.->|"Decision: BLOCK / REVIEW"| G3
```

The decision path is strictly deterministic — no non-deterministic LLMs in the critical decision loop. It checks delegated actions, principal identity, amount limits, targets, sensitive operations, and authenticated integration boundaries. Every response includes policy results and a tamper-proof SHA-256 canonical receipt hash.

Status: experimental v0.3.0, deployed on Cloudflare Workers edge. Since v0.3.0, authority can be **proved** rather than asserted: a principal signs a delegation grant, Vizier verifies it against a registered public key, and the receipt records authority provenance. Read the [threat model](docs/THREAT_MODEL.md) before placing this service in an execution path.

---

## 🌐 Public Surfaces

- **Edge Worker**: <https://vizier.vassiliy-lakhonin.workers.dev>
- **Action Playground**: <https://vizier.vassiliy-lakhonin.workers.dev/playground>
- **Live Field Reference**: <https://vizier.vassiliy-lakhonin.workers.dev/docs>
- **OpenAPI 3.1 Contract**: <https://vizier.vassiliy-lakhonin.workers.dev/openapi.json>
- **AI Discovery Catalog**: <https://vizier.vassiliy-lakhonin.workers.dev/.well-known/ai-catalog.json>
- **MCP Server Manifest**: <https://vizier.vassiliy-lakhonin.workers.dev/.well-known/mcp.json>
- **MCP Registry Entry**: `io.github.vassiliylakhonin/vizier`
- **Agent Card**: <https://vizier.vassiliy-lakhonin.workers.dev/.well-known/agent-card.json>
- **Public Key Set (JWKS)**: <https://vizier.vassiliy-lakhonin.workers.dev/.well-known/jwks.json>

---

## 🚀 Quickstarts

### 1. Python SDK (`vizier-guard`)

Zero external dependencies (Python standard library only):

```bash
pip install vizier-guard
```

```python
from vizier import VizierClient, vizier_guard

client = VizierClient(
    base_url="https://vizier.vassiliy-lakhonin.workers.dev",
    api_key="your-api-key"
)

# Protect any function or tool:
@vizier_guard(
    client=client,
    action_type="purchase",
    max_amount=500.0,
    currency="USD",
    allowed_targets=["supplier.example"]
)
def execute_order(amount: float, target: str):
    # Runs ONLY if Vizier decision is ALLOW
    return {"status": "success", "amount": amount}

execute_order(amount=450.0, target="supplier.example")   # Allowed
execute_order(amount=1200.0, target="supplier.example")  # Raises ActionBlockedError
```

#### LangChain / LangGraph & CrewAI:

```python
from vizier.integrations.langchain import VizierLangChainToolGuard
from vizier.integrations.crewai import VizierCrewAIToolGuard

# LangChain / LangGraph
safe_tool = VizierLangChainToolGuard(
    tool=my_search_tool,
    client=client,
    allowed_actions=["search"],
    max_amount=0.0
)

# CrewAI
safe_crew_tool = VizierCrewAIToolGuard(
    tool=my_payment_tool,
    client=client,
    max_amount=250.0
)
```

#### Human-in-the-Loop (Telegram / CLI / Webhooks) & Async:

```python
from vizier import AsyncVizierClient, vizier_guard, TelegramHITLHandler

# Interactive approval buttons via Telegram Bot when decision is REVIEW
telegram_approver = TelegramHITLHandler(
    bot_token=os.environ["TELEGRAM_BOT_TOKEN"],
    chat_id=os.environ["TELEGRAM_CHAT_ID"]
)

@vizier_guard(
    client=AsyncVizierClient(),
    action_type="transfer_funds",
    hitl_handler=telegram_approver
)
async def transfer(amount: float, target: str):
    # Executes ONLY if human operator clicks [Approve] in Telegram
    return await bank_api.send(amount, target)
```

#### MCP Server for Claude Desktop & Cursor:

Equip Claude Desktop or Cursor with deterministic guardrails (`vizier_screen_action`, `vizier_verify_receipt`, `vizier_check_policy`):

```json
{
  "mcpServers": {
    "vizier": {
      "command": "uvx",
      "args": ["vizier-guard", "mcp"],
      "env": {
        "VIZIER_BASE_URL": "https://vizier.vassiliy-lakhonin.workers.dev",
        "VIZIER_API_KEY": "your-vizier-api-key"
      }
    }
  }
}
```

---

### 2. MCP Enforcement Proxy CLI

Wrap any local or remote MCP server with deterministic authorization:

```bash
npx @vizier/mcp-proxy \
  --upstream http://localhost:3000/mcp \
  --tools "query_db,execute_command,fetch_api" \
  --vizier https://vizier.vassiliy-lakhonin.workers.dev \
  --api-key $VIZIER_API_KEY
```

---

### 3. TypeScript SDK (`@vizier/sdk`)

```bash
npm install @vizier/sdk
```

```ts
import { Vizier } from "@vizier/sdk";

const vizier = new Vizier({
  baseUrl: "https://vizier.vassiliy-lakhonin.workers.dev",
  apiKey: process.env.VIZIER_API_KEY,
});

const decision = await vizier.verify({
  agent: { id: "agent-01", owner: "acme-corp" },
  principal: { id: "acme-corp" },
  action: {
    type: "purchase",
    target: "supplier.example",
    parameters: { amount: 820, currency: "USD" }
  },
  authority: {
    allowed_actions: ["purchase"],
    constraints: { max_amount: 1000, currency: "USD" }
  },
  context: { source: "rest" }
});

if (decision.decision === "ALLOW") {
  // Execute protected operation
}
```

---

### 4. Direct HTTP / cURL

```bash
curl -sS https://vizier.vassiliy-lakhonin.workers.dev/v1/verify \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_KEY' \
  -d '{
    "agent": { "id": "agent-01", "owner": "acme" },
    "principal": { "id": "acme" },
    "action": {
      "type": "purchase",
      "target": "supplier.example",
      "parameters": { "amount": 820, "currency": "USD" }
    },
    "authority": {
      "allowed_actions": ["purchase"],
      "constraints": { "max_amount": 1000, "currency": "USD" }
    },
    "context": { "source": "rest" }
  }'
```

---

## 🛑 Agent Circuit Breaker & Loop Killer

Infinite tool loops and runaway retry storms are among the most catastrophic failure modes of autonomous agents — in minutes, an agent stuck in a loop can exhaust external API rate limits, burn through thousands of dollars in LLM tokens, or flood production databases.

Vizier provides built-in circuit breakers across both Python and MCP environments:

* **Sliding-Window Loop Detection**: Computes deterministic SHA-256 canonical JSON hashes of tool arguments. If the same tool is invoked repeatedly within a sliding window (e.g. 3 times in 30 seconds), the circuit trips immediately (`CIRCUIT_TRIPPED:LOOP_DETECTED`).
* **Session Action Budgets**: Caps the total number of actions an agent can execute within a single task or session (`CIRCUIT_TRIPPED:BUDGET_EXCEEDED`).
* **Python Guard Decorator**:
  ```python
  from vizier import CircuitBreaker, vizier_guard

  breaker = CircuitBreaker(max_repeated_calls=3, time_window_seconds=30.0, max_session_actions=25)

  @vizier_guard(action_type="query_db", circuit_breaker=breaker)
  def query_database(query: str):
      return db.execute(query)
  ```
* **MCP Enforcement Proxy**:
  ```typescript
  const proxy = createMcpEnforcementProxy({
    // ...
    circuitBreaker: { maxRepeats: 3, windowMs: 30_000 },
  });
  ```
  Returns standardized JSON-RPC 2.0 error `-32028` on tripped loops without invoking the upstream tool.

---

## Proving the authority instead of asserting it

By default the `author