# Korven — AIP Protocol (Full Technical Reference)

> The identity and intent verification protocol for autonomous AI agents. Like HTTPS, but for AI-to-AI communication.

## What is AIP?

AIP (Agent Identity Protocol) is an open-source cryptographic protocol that provides:

1. **Verifiable identity** for every AI agent via Ed25519-signed passports
2. **Intent verification** through an 8-step pipeline before every action
3. **Action boundary enforcement** preventing agents from exceeding their scope
4. **Real-time revocation** (kill switch) with zero propagation delay
5. **Bayesian trust scoring** tracking agent reputation over time
6. **Monetary limits** capping per-transaction and total spending

AIP solves the "rogue AI agent" problem — the risk that autonomous agents act beyond their authorized scope, get prompt-injected, or behave maliciously.

## Why AIP Matters

As AI agents become autonomous (booking flights, executing trades, sending emails), there is no standard way to:
- Verify an agent's identity cryptographically
- Enforce what actions an agent is allowed to take
- Instantly shut down a compromised agent
- Track an agent's trustworthiness over time

AIP is the answer. It's the security layer between AI agents and the real world.

## Installation

```bash
pip install aip-protocol
```

## Quick Start (3 API Calls)

### 1. Create an Agent Passport
```bash
curl -X POST https://aip.synthexai.tech/api/passports \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "finance",
    "agent_name": "trading-bot",
    "allowed_actions": ["execute_trade", "check_balance"],
    "monetary_limit_per_txn": 1000.0
  }'
```

Response includes:
- `agent_id`: Unique agent identifier
- `did`: Decentralized Identifier (did:aip:...)
- `public_key`: Ed25519 public key
- `private_key`: Ed25519 private key (shown once, save it!)

### 2. Verify an Intent Before Every Action
```bash
curl -X POST https://aip.synthexai.tech/api/verify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "...",
    "action": "execute_trade",
    "target": "AAPL",
    "amount": 500.0,
    "signature": "..."
  }'
```

The 8-step verification pipeline checks:
1. Schema validation
2. Agent existence
3. Revocation status
4. Intent signature (Ed25519)
5. Action boundary check
6. Monetary limit check
7. Geo-restriction check
8. Trust score threshold

### 3. Revoke an Agent (Kill Switch)
```bash
curl -X POST https://aip.synthexai.tech/api/revoke \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "...",
    "reason": "Suspicious trading activity detected"
  }'
```

## Python SDK Usage

```python
from aip_protocol import create_passport, sign_intent, verify_intent, revoke_agent

# Create
passport = create_passport("finance", "trading-bot", ["execute_trade"], 1000.0)

# Sign an intent
envelope = sign_intent(
    passport, action="execute_trade", target="AAPL", amount=500.0
)

# Verify (returns True/False + 8 check results)
result = verify_intent(envelope, passport)

# Revoke
revoke_agent(passport.agent_id, reason="compromised")
```

### Shield Decorator (Zero-Config Protection)

```python
from aip_protocol import shield

@shield(passport, allowed_actions=["search", "summarize"])
def my_agent_function(query: str):
    # Every call is automatically signed + verified
    return search(query)
```

## Framework Integrations

### LangChain
```bash
pip install aip-langchain
```
```python
from aip_langchain import aip_tool

@aip_tool(passport, action="search_web")
def search(query: str) -> str:
    """Search the web for information."""
    return results
```

### CrewAI
```bash
pip install aip-crewai
```
```python
from aip_crewai import aip_agent, aip_task

agent = aip_agent(
    crew_agent, passport,
    allowed_actions=["research", "write"]
)
task = aip_task(crew_task, passport, action="research")
```

### AutoGen
```bash
pip install aip-autogen
```
```python
from aip_autogen import aip_wrap

protected_agent = aip_wrap(
    autogen_agent, passport,
    allowed_actions=["code_review", "suggest_fix"]
)
```

## API Endpoints

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| POST | /api/register | None | Create account |
| POST | /api/token | None | Get JWT token |
| POST | /api/passports | JWT | Create agent passport |
| GET | /api/passports | JWT | List all passports |
| POST | /api/verify | API Key | Verify agent intent |
| POST | /api/revoke | API Key | Revoke agent |
| POST | /api/reinstate | API Key | Reinstate agent |
| POST | /api/suspend | API Key | Suspend agent |
| GET | /api/analytics/{id} | JWT | Get agent analytics |
| GET | /api/trust-score/{id} | API Key | Get trust score |
| POST | /api/keys | JWT | Create API key |
| GET | /api/keys | JWT | List API keys |
| DELETE | /api/keys/{id} | JWT | Revoke API key |
| GET | /api/verifications | JWT | Verification history |

## Error Codes

| Code | HTTP | Meaning |
|------|------|---------|
| AIP-E001 | 400 | Missing required fields |
| AIP-E002 | 404 | Agent not found |
| AIP-E003 | 403 | Agent revoked |
| AIP-E004 | 403 | Invalid signature |
| AIP-E005 | 403 | Action not allowed |
| AIP-E006 | 403 | Monetary limit exceeded |
| AIP-E007 | 403 | Geo-restriction violated |
| AIP-E008 | 403 | Trust score below threshold |
| AIP-E009 | 429 | Rate limit exceeded |
| AIP-E010 | 403 | Agent suspended |

## Security Model

- **Cryptography**: Ed25519 signatures (RFC 8032)
- **Identity**: Decentralized Identifiers (DIDs) — did:aip:{agent_id}
- **Canonical serialization**: Deterministic JSON for signature stability
- **EUF-CMA security**: Existential unforgeability under chosen-message attacks
- **Zero-delay revocation**: No CRL propagation — revocation is immediate
- **Trust model**: Bayesian scoring with Beta distribution (α/β parameters)

## TypeScript SDK

```bash
npm install @anthropic-ai/aip-protocol
```

```typescript
import { createPassport, signIntent, verifyIntent } from '@anthropic-ai/aip-protocol';
```

## Pricing

| Plan | Price | Agents | Verifications/mo |
|------|-------|--------|-----------------|
| Starter | Free | 3 | 500 |
| Team | $29/mo | 25 | 10,000 |
| Enterprise | Custom | Unlimited | Unlimited |

## Links

- Website: https://aip.synthexai.tech
- Documentation: https://aip.synthexai.tech/docs
- Getting Started: https://aip.synthexai.tech/docs/getting-started
- PyPI: https://pypi.org/project/aip-protocol/
- API Base URL: https://aip.synthexai.tech/api

## Contact

- Website: https://aip.synthexai.tech
- Email: Available through the platform