# eyeVesa — Identity & Trust Layer for AI Agents

## 1. Problem Statement

Autonomous AI agents need to interact with enterprise systems — databases, Kubernetes, payment gateways, APIs — but existing access control (OAuth, API keys, IAM roles) assumes a human at the keyboard. Agents operate autonomously, at machine speed, with no human in the loop by default. This creates four unsolved problems:

- **Identity**: How does a system know which agent is calling, and that it hasn't been tampered with?
- **Authorization**: How do you express and enforce fine-grained policies for agent actions (e.g., "deploy to staging OK, prod requires approval")?
- **Audit**: How do you produce tamper-proof, non-repudiable records of every agent action?
- **Trust**: How do you detect anomalous agent behavior and adjust trust dynamically?

eyeVesa solves all four with a gateway that sits between AI agents and their target resources.

## 2. Architecture Overview

```text
┌──────────────┐     ┌──────────────────────────────────────┐     ┌──────────────────┐
│              │     │          eyeVesa Gateway             │     │                  │
│   AI Agent   │────▶│  ┌────────────┐  ┌────────────────┐  │────▶│    Resource      │
│  (MCP SDK)   │     │  │ Rust Core  │  │  Go Control    │  │     │    Adapter       │
│              │◀────│  │ Proxy      │  │  Plane         │  │◀────│  (MCP wrapper)   │
└──────────────┘     │  │ :9443      │  │ :8080 / :9090  │  │     └──────────────────┘
                     │  └─────┬──────┘  └───────┬────────┘  │
                     │        │                  │          │
                     │        │         ┌────────┴───────┐  │
                     │        │         │  PostgreSQL    │  │
                     │        │         │  (state store) │  │
                     │        │         └────────────────┘  │
                     │        │                             │
                     │  ┌─────┴──────┐                      │
                     │  │  OPA       │                      │
                     │  │  (:8181)   │                      │
                     │  └────────────┘                      │
                     └──────────────────────────────────────┘
```

### 2.1 Rust Core Proxy (:9443)

The hot path. All agent MCP (Model Context Protocol) requests hit this proxy first.

Responsibilities:
- Terminate mTLS from agent SDKs
- Verify Ed25519 agent signatures
- Verify PTV (Process Trait Verification) attestations
- Cache agent identity and policy decisions for low latency
- Forward authorized MCP requests to the appropriate Resource Adapter
- Route non-MCP requests (registration, policy management, HITL, audit) to Go Control Plane
- Fast-path authorization via gRPC to Go Control Plane

### 2.2 Go Control Plane (:8080 HTTP, :9090 gRPC)

The control plane. Owns all business logic and persistent state.

Responsibilities:
- Agent registration and lifecycle management
- Resource registration and management
- OPA Rego policy management (CRUD + evaluation)
- Human-in-the-loop (HITL) workflows, escalations, and notifications
- PTV attestation verification
- Delegation chain verification
- Audit log and narrative management
- Trust score calculation and behavioral anomaly detection
- Budget metering and rate limiting
- Multi-tenancy and approver management
- Push notifications (APNs, FCM, Slack, PagerDuty, Webhook, Telegram, Discord)
- SPIFFE/SPIRE federation support
- Metrics exposition

### 2.3 PostgreSQL

Persistence for all control plane state. Key tables include:
- `agents` — agent records with public keys, capabilities, metadata
- `resources` — resource/tool definitions
- `policies` — Rego policy documents
- `audit_logs` — Ed25519-signed audit entries
- `trust_events` — trust score adjustments
- `hitl_approvals`, `hitl_approval_chain`, `hitl_escalation_config`, `hitl_notifications` — HITL lifecycle and escalations
- `delegations` — issued delegation chains
- `identity_bindings` — mapped external identities to agents
- `tenants`, `approvers` — multi-tenancy and dedicated approvers
- `behavioral_events`, `behavioral_anomalies` — ML-based embedding events for anomaly detection
- `hitl_summaries`, `audit_narratives`, `policy_translations`, `llm_config` — AI-powered explanations
- `agent_spend`, `rate_limit_counters` — budget and rate limit tracking
- `push_tokens`, `api_keys` — notification tokens and API keys
- `trust_bundles`, `workload_registrations` — SPIRE federation states

### 2.4 OPA (Open Policy Agent) (:8181)

Stateless policy engine. Evaluates Rego rules on structured input (agent, action, resource, context). eyeVesa manages OPA lifecycle via its REST API.

### 2.5 Resource Adapter (:8443)

Wraps external enterprise APIs (Kubernetes, AWS, databases, Slack, payment gateways) as MCP-compatible tools. Receives proxy calls from the Rust Core after authorization.

## 3. Agent Identity & Federation

Every agent gets a cryptographic identity at registration:

- **Ed25519 keypair**: agent signs every MCP request. Gateway verifies the signature before processing.
- **Agent ID**: UUID v4
- **Owner**: `org:devops` or `user:alice` — the entity responsible for the agent
- **Capabilities & Tools**: Declarative actions the agent is allowed to perform
- **PTV Expected Hash**: Baseline measurement for runtime integrity verification

**SPIFFE/SPIRE Federation:** eyeVesa integrates with `go-spiffe/v2` to support federated X.509 SVID workloads, allowing agents running in external environments to natively authenticate via trust bundles.

## 4. Authorization Model (3-Tier OPA)

Every agent action goes through policy evaluation. Three outcomes:

| Outcome | Meaning |
|---|---|
| **allow** | Action proceeds immediately |
| **hitl** | Human must approve |
| **deny** | Action rejected |

Policy Rego receives the full request context (agent, capabilities, action, resource, trust score). Policies can also automatically translate to human-readable text via LLM capabilities.

## 5. Human-in-the-Loop (HITL) & Escalation

When OPA returns `decision = "hitl"`, the action is paused until a human approves or rejects.

### HITL Lifecycle & Escalations

If a primary approver doesn't respond in time, eyeVesa uses `hitl_escalation_config` to escalate to secondary approvers. LLM integration generates concise `hitl_summaries` so approvers instantly understand what the agent is requesting. Notifications are routed to Slack, PagerDuty, Webhooks, APNs/FCM `push_tokens`, Telegram, and Discord.

## 6. PTV (Process Trait Verification) & Behavioral Anomaly Detection

**PTV** ensures the agent process hasn't been tampered with (detects code injection, binary replacement). At request time, agents include a signed attestation of their memory/state. 

**Behavioral Embeddings**: The gateway records agent behaviors as vector embeddings. Any deviation from the norm triggers a `behavioral_anomaly` and decays the trust score.

## 7. Trust Scoring & Budgets

Continuous trust scoring evaluates agent behavior. Successes increase trust incrementally, while anomalies, PTV failures, or policy denials rapidly decay it. Low trust can force HITL or full denial.

**Budget Metering**: Agents have financial (`agent_spend`) and throughput (`rate_limit_counters`) limits. Even fully trusted agents are blocked if they exceed their budget constraints, preventing runaway costs.

## 8. Agent Delegation

Agents can delegate authority to sub-agents, creating a verifiable chain of trust. 
The Rust Proxy verifies that the entire delegation chain is cryptographically intact and the action is within the delegated scope.

## 9. Audit Log & LLM Narratives

Every authorized action produces an Ed25519-signed audit entry. To make audit trails accessible to non-technical auditors, eyeVesa uses the `audit_narratives` LLM integration to generate plain-english descriptions of each logged event.

## 10. Skills System

eyeVesa includes a full skills management subsystem. Skills are declared capabilities that can be assigned to agents, endorsed by peers, and verified by trusted authorities.

- **Skill Registry**: CRUD for skills with name, description, category, risk level
- **Assignment**: Assign skills to agents with proficiency (beginner/intermediate/expert)
- **Endorsement Chain**: Agents endorse each other's skills, building verifiable reputation
- **Trust Scoring**: Per-skill trust scores that feed into OPA policy evaluation
- **Search**: Find agents by skill, and identify missing skills

## 11. Transaction Protocol

A complete capability token and receipt system for agent-to-agent and agent-to-merchant transactions:

- **Capability Tokens**: Ed25519-signed tokens proving an agent has authority to perform specific actions within a scope and time window
- **Transaction Receipts**: Verifiable, non-repudiable proof that a token was used for a specific action
- **Revocation**: Centralized revocation store for compromised or expired tokens
- **Use Cases**: Agent purchases from software marketplaces, cross-agent resource delegation

## 12. Airport — Agent Discovery & Mesh

Airport is eyeVesa's agent discovery and dispatch hub:

- **Heartbeat**: Agents broadcast presence with capabilities, location, and uptime
- **Search**: Query online agents by capability, trust level, or tags
- **Profiles**: Each agent maintains a discoverable airport profile
- **Connections**: Track active agent-to-agent connections in a mesh topology
- **Dispatch**: Route tasks to capable agents based on proximity and trust

## 13. Key Rotation

Ed25519 signing keys can be rotated without downtime:
- Rotate with configurable grace period (previous key remains valid)
- Track rotation history with timestamps
- Clear previous keys after grace expiry

## 14. Push Notifications

Device push notification management for HITL approvals and alerts:
- Register iOS (APNs) and Android (FCM) device tokens
- List and deactivate tokens
- Used by the HITL escalation system for instant human notifications

## 15. Multi-Tenancy & License-Gated Features

eyeVesa natively supports multi-tenancy and license-gated pro features:
- **Tenants**: Scoped isolation of agents, resources, policies, and audit logs
- **Approvers**: Dedicated approver pools per tenant for HITL
- **License Features**: Multi-layer HITL escalation, LLM integration (summaries, narratives, policy translation), behavioral anomaly detection, multi-tenancy, budget metering, push notifications

## 16. Gateway Modes

| Mode | Description | Use Case |
|---|---|---|
| `plaintext` | No TLS between agent and gateway | Local development |
| `tls` | Server-side TLS | Internal networks, staging |
| `mtls` | Mutual TLS (client certs) | Production |

## 23. Terminal UI (TUI)

eyeVesa ships with an interactive, keyboard-driven Terminal Dashboard (`eyevesa tui`) to visually monitor gateway status, browse agents, inspect resources, manage pending HITL approvals, and view audit trails.

## 24. CLI Reference

The `eyevesa` CLI covers all operations. **22 parent commands, 85+ subcommands:**

```bash
# Agent operations
eyevesa agents register --name bot --owner org:devops --capabilities "read"
eyevesa agents list
eyevesa agents get <id>
eyevesa agents trust <id>

# Authorization
eyevesa authorize --agent-id <id> --action read --resource-id <rid>

# HITL approvals
eyevesa hitl list
eyevesa hitl approve <hitl-id>
eyevesa hitl deny <hitl-id>
eyevesa hitl status <hitl-id>
eyevesa hitl request --action deploy --reason "prod deploy" --risk-level high
eyevesa hitl escalate <hitl-id>

# Delegation
eyevesa delegate create --parent <id> --child <id> --scope "log_search" --max-depth 1
eyevesa delegate list <agent-id>
eyevesa delegate revoke <delegation-id>
eyevesa delegate validate <delegation-id>

# Audit
eyevesa audit --agent-id <id> --limit 50

# Resources
eyevesa resource register --name k8s --type kubernetes --endpoint ...
eyevesa resource list
eyevesa resource get <id>

# MCP
eyevesa mcp initialize
eyevesa mcp tools-list
eyevesa mcp call <tool> --params '{"key":"val"}'

# Skills (11 subcommands)
eyevesa skills list --category monitoring
eyevesa skills search --query "kubernetes"
eyevesa skills create --name k8s-deploy --description "Deploy to K8s" --category ops
eyevesa skills assign --agent-id <id> --skill-id <sid> --proficiency expert
eyevesa skills endorse --agent-id <id> --skill-id <sid>
eyevesa skills trust <agent-id>

# Transaction Protocol (6 subcommands)
eyevesa tx issue --subject <agent-id> --scope '{"read":true}' --ttl 3600
eyevesa tx verify <token-id>
eyevesa tx revoke <token-id> --reason "compromised"
eyevesa tx receipt --token-id <tid> --action purchase --value 50

# SPIRE Federation (13 subcommands)
eyevesa spire create-bundle --name prod-cluster --domain prod.example.org
eyevesa spire list-bundles
eyevesa spire register-workload --spiffe-id spiffe://prod/k8s/my-svc --selectors "k8s:..."
eyevesa spire attest-workload <workload-id>
eyevesa spire status

# Airport Discovery (7 subcommands)
eyevesa airport search --capability "database"
eyevesa airport online
eyevesa airport profile <agent-id>
eyevesa airport heartbeat
eyevesa airport connections

# Budget & Rate Limits
eyevesa budget check --agent-id <id>
eyevesa budget record --agent-id <id> --amount 10 --resource "api-call"

# Key Rotation
eyevesa keys rotate
eyevesa keys status
eyevesa keys clear-previous

# Tenants
eyevesa tenants create --name acme-corp --domain acme.com
eyevesa tenants list
eyevesa tenants get <tenant-id>

# Push Notifications
eyevesa push register --token <device-token> --platform ios
eyevesa push list
eyevesa push deactivate <token-id>

# PTV Attestation
eyevesa ptv attest --platform tpm2.0 --firmware-version 2.1
eyevesa ptv verify <binding-id>

# Other
eyevesa init                   # Interactive agent registration wizard
eyevesa config show            # Show current config
eyevesa doctor                 # Diagnostic checks
eyevesa ready                  # Readiness check
eyevesa discover               # Explore resources + MCP tools
eyevesa verify-signature <agent-id> <message> <signature>
eyevesa tui                    # Full terminal dashboard

# Authentication
eyevesa auth api-key create --label "ci-cd"
eyevesa auth api-key list
eyevesa auth api-key revoke <key-id>
```

## 25. Hermes Agent SDK Integration

Hermes is a Python agent framework that integrates natively with eyeVesa. It automates keypair generation, handles mTLS, auto-signs MCP requests, transparently performs PTV attestations, and natively blocks/waits during HITL decisions.

## 26. Integration with Major LLM Providers

eyeVesa supports integration with Agentic AI systems from Claude, OpenAI, Anthropic, Grok, Gemini, Llama, LangGraph, CrewAI, and AutoGen. Integration is done via:
- **Rust SDK** (`sdk/agent-sdk-rust/`) — For native Rust-based agents (e.g. Grok)
- **MCP Protocol** (`/v1/mcp`) — For agents supporting the Model Context Protocol (e.g. Claude Computer Use)
- **REST API + JWT/API Key** — For custom tool calling capabilities (e.g. OpenAI o1/GPT-4o, Gemini, Llama)

## 27. Quick Services Reference

| Service | Port | Start Command |
|---|---|---|
| Go Control Plane (HTTP) | 8080 | `cd gateway/control-plane && go run cmd/api/main.go` |
| Go Control Plane (gRPC) | 9090 | (same process, different listener) |
| Rust Core Proxy | 9443 | `cd gateway/core && cargo run --release` |
| Resource Adapter | 8443 | `cd adapter/resource-adapter-go && go run ./cmd/` |
| PostgreSQL | 5432 | `docker-compose up -d postgres` |
| OPA | 8181 | `docker-compose up -d opa` |

**Environment & Setup:**
- Database: `agentid` on `localhost:5432`, user `agentid`, password `agentid_dev`
- Keys: Ed25519 at `GATEWAY_KEY_PATH`, PTV ECDSA at `PTV_KEY_PATH`
- Migrations: `psql -h localhost -U agentid -d agentid -f registry/migrations/NNN_*.sql`

## 28. Agent SDK

First-party SDKs for Python, Rust, and TypeScript. All three provide Ed25519 identity, MCP invocation, HITL approvals, PTV attestation, delegation, skills management, and a transaction protocol.

| Feature | Python | Rust | TypeScript |
|---|---|---|---|
| Package | agentid-sdk | agentid-sdk | agentid-sdk |
| Registration | connect() | AgentClient::connect() | connect() |
| MCP Invoke | invoke() | client.invoke() | invoke() |
| Ed25519 | PyNaCl | ed25519-dalek | tweetnacl |
| HITL | request_approval() | client.request_approval() | requestApproval() |
| PTV | attest() / bind() | client.attest() / bind() | attest() / bind() |
| Delegation | delegate() | client.delegate() | delegate() |
| Skills | create_skill() / assign_skill() | client.create_skill() / assign() | createSkill() / assignSkill() |
| Token TX | issue_token() / issue_receipt() | - | issueToken() / issueReceipt() |
| Framework integrations | LangGraph, CrewAI, AutoGen | - | LangGraph, CrewAI, AutoGen |
| from_env() | Yes | No | Yes |
| Min version | Python 3.10+ | Rust 2021 Edition | Node 18+ |
| HTTP | httpx.AsyncClient | reqwest | fetch() (native) |