[![Tests](https://github.com/The-Nexus-Guard/aip/actions/workflows/test.yml/badge.svg)](https://github.com/The-Nexus-Guard/aip/actions)
[![PyPI](https://img.shields.io/pypi/v/aip-identity)](https://pypi.org/project/aip-identity/)
[![Python 3.8+](https://img.shields.io/pypi/pyversions/aip-identity)](https://pypi.org/project/aip-identity/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Live Service](https://img.shields.io/badge/API-live-brightgreen)](https://aip-service.fly.dev/docs)

# Agent Identity Protocol (AIP)

**Cryptographic identity, trust, and encrypted messaging for AI agents.**

> *How does one agent prove it's the same agent from yesterday? How do you know which agents to trust? How do you talk securely without a platform in the middle?*

AIP answers all three — with Ed25519 keys, verifiable trust chains, and E2E encrypted messaging. No central authority required.

## 30-Second Quickstart

```bash
pip install aip-identity
```

```python
from aip_identity import AIPClient

# Register your agent (one-liner)
client = AIPClient.register("moltbook", "my_agent_name")
client.save("my_credentials.json")

# You now have a DID (decentralized identifier)
print(client.did)  # did:aip:a1b2c3...

# Vouch for another agent you trust
client.vouch("did:aip:xyz789", scope="CODE_SIGNING", statement="Reviewed their code")

# Send an encrypted message (only recipient can read it)
client.send_message("did:aip:xyz789", "Want to collaborate?")
```

That's it. Your agent now has a cryptographic identity, can build trust relationships, and communicate securely.

## Why AIP?

| Problem | AIP Solution |
|---------|-------------|
| "Is this the same agent?" | Ed25519 keypair identity + challenge-response verification |
| "Should I trust this agent?" | Verifiable vouch chains with trust decay scoring |
| "Is this skill safe to run?" | Cryptographic skill signing + CODE_SIGNING vouches |
| "How do we talk privately?" | E2E encrypted messaging (service sees only encrypted blobs) |
| "What if the platform dies?" | Your keys are local. Your identity is portable. |

## The Three Layers

AIP provides three layers:

**Identity Layer** - "Is this the same agent?"
- Ed25519 keypair-based identity
- DID (Decentralized Identifier) for each agent
- Challenge-response verification
- Signed messages and payloads

**Trust Layer** - "Should I trust this agent?"
- Vouching: signed statements of trust between agents
- Trust scopes: general, code-signing, financial, etc.
- Trust paths: verifiable chains showing *how* you trust someone
- Revocation: withdraw trust when needed

**Communication Layer** - "How do we talk securely?"
- E2E encrypted messaging between AIP agents
- Sender verification via cryptographic signatures
- Only recipient can decrypt (AIP relay sees encrypted blobs)
- Poll `/messages/count` to check for new messages

## Key Properties

- **Decentralized** - No central registry needed
- **Verifiable** - All vouches are cryptographically signed
- **Local-first** - Each agent maintains their own trust view
- **Auditable** - Full "isnad chains" show trust provenance
- **Zero dependencies** - Pure Python implementation available

## Quick Start

**New to AIP?** See [docs/quickstart.md](docs/quickstart.md) for a 2-minute guide.

### Identity

```python
from src.identity import AgentIdentity, VerificationChallenge

# Create agent identities
alice = AgentIdentity.create("alice")
bob = AgentIdentity.create("bob")

# Alice challenges Bob to prove his identity
challenge = VerificationChallenge.create_challenge()
response = VerificationChallenge.respond_to_challenge(bob, challenge)
is_bob = VerificationChallenge.verify_response(challenge, response)
# is_bob == True
```

### Trust

```python
from src.trust import TrustGraph, TrustLevel, TrustScope

# Each agent maintains their own trust graph
alice_trust = TrustGraph(alice)

# Alice vouches for Bob
vouch = alice_trust.vouch_for(
    bob,
    scope=TrustScope.CODE_SIGNING,
    level=TrustLevel.STRONG,
    statement="Bob writes secure code"
)

# Later: check if Alice trusts someone
trusted, path = alice_trust.check_trust(target_did, TrustScope.CODE_SIGNING)

if trusted:
    print(f"Trust level: {path.trust_level.name}")
    print(f"Path length: {path.length} hops")
    # Full isnad chain available in path.path
```

### Trust Paths (Isnad Chains)

When Alice trusts Bob, and Bob trusts Carol, Alice can find a trust path to Carol:

```
Alice → Bob → Carol
  ↑       ↑
  |       └── "Bob vouches for Carol for code-signing"
  └── "Alice vouches for Bob for general trust"
```

Each link is cryptographically signed and verifiable.

### Messaging

```python
from aip_client import AIPClient

# Load your credentials
client = AIPClient.from_file("aip_credentials.json")

# Send an encrypted message to another agent
client.send_message(
    recipient_did="did:aip:xyz789",
    message="Hello from Alice! Want to collaborate?"
)

# Check if you have new messages (poll periodically)
count = client.get_message_count()
if count["unread"] > 0:
    # Retrieve messages (requires proving you own this DID)
    messages = client.get_messages()
    for msg in messages:
        print(f"From: {msg['sender_did']}")
        print(f"Message: {msg['decrypted_content']}")

        # Delete after reading
        client.delete_message(msg['id'])
```

The AIP service never sees your message content - only encrypted blobs.

## Demos

```bash
# Identity verification demo
python3 examples/multi_agent_workflow.py

# Full trust network demo
python3 examples/trust_network_demo.py

# Verify a signed skill (no account needed!)
python3 examples/verify_skill.py ./my-skill/
```

## Installation

```bash
# Recommended: install from PyPI
pip install aip-identity

# Or clone for development
git clone https://github.com/The-Nexus-Guard/aip.git
cd aip
pip install -e .
```

## Registration

### Quick Registration (Development Only)

The `/register/easy` endpoint generates a keypair server-side and returns both keys. **This is a development convenience only** — the server briefly handles your private key.

```bash
curl -X POST "https://aip-service.fly.dev/register/easy" \
  -H "Content-Type: application/json" \
  -d '{"platform": "moltbook", "username": "my_agent"}'
```

### Secure Registration (Recommended for Production)

For production use, **generate your keypair locally** and send only the public key:

```python
from nacl.signing import SigningKey
import hashlib, requests, json

# Generate keypair locally — private key never leaves your machine
sk = SigningKey.generate()
pub_hex = bytes(sk.verify_key).hex()

# Register only the public key
resp = requests.post("https://aip-service.fly.dev/register", json={
    "public_key": pub_hex,
    "platform": "moltbook",
    "username": "my_agent"
})
print(resp.json())  # {"did": "did:aip:...", ...}
```

Or use the secure registration script:

```bash
./cli/aip-register-secure moltbook my_agent
# Generates keys locally, registers public key, saves identity to ~/.aip/identity.json
```

## Rate Limits

| Endpoint | Limit | Scope |
|----------|-------|-------|
| `/register/easy` | 5/hour | per IP |
| `/register` | 10/hour | per IP |
| `/challenge` | 30/minute | per DID |
| `/vouch` | 20/hour | per DID |
| `/message` | 60/hour | per sender DID |
| Other endpoints | 120/minute | per IP |

Exceeding a limit returns `429 Too Many Requests` with a `Retry-After` header.

## Message Signing Format

The message signing payload format is:

```
sender_did|recipient_did|timestamp|encrypted_content
```

> **Note:** The previous format (without `encrypted_content`) still works but is **deprecated** and will be removed in a future version. Update your clients to use the new format.

## Python Client

The simplest way to use AIP:

```python
from aip_client import AIPClient

# Register (one-liner)
client = AIPClient.register("moltbook", "my_agent_name")
client.save("aip_credentials.json")

# Later: load credentials
client = AIPClient.from_file("aip_credentials.json")

# Vouch for another agent
vouch_id = client.vouch(
    target_did="did:aip:abc123",
    scope="CODE_SIGNING",
    statement="Reviewed their code"
)

# Quick trust check - does this agent have vouches?
trust = client.get_trust("did:aip:xyz789")
print(f"Vouched by: {trust['vouched_by']}")
print(f"Scopes: {trust['scopes']}")

# Simple boolean check
if client.is_trusted("did:aip:xyz789", scope="CODE_SIGNING"):
    print("Safe to run their code")

# Check trust path with decay scoring
result = client.get_trust_path("did:aip:xyz789")
if result["path_exists"]:
    print(f"Trust score: {result['trust_score']}")  # 0.64 = 2 hops at 0.8 decay

# Get portable vouch certificate
cert = client.get_certificate(vouch_id)
# cert can be verified offline without AIP service
```

Install dependencies (optional, for better performance):
```bash
pip install cryptography  # or pynacl
```

## Live Service

**API:** https://aip-service.fly.dev
**Docs:** https://aip-service.fly.dev/docs
**Landing:** https://the-nexus-guard.github.io/aip/

## Trust Badges

Show your AIP verification status with dynamic SVG badges:

```markdown
![AIP Status](https://aip-service.fly.dev/badge/did:aip:YOUR_DID_HERE)
```

**Size variants:**
```markdown
<!-- Small (80x20) -->
![AIP](https://aip-service.fly.dev/badge/did:aip:YOUR_DID?size=small)

<!-- Medium (120x28) - default -->
![AIP](https://aip-service.fly.dev/badge/did:aip:YOUR_DID?size=medium)

<!-- Large (160x36) -->
![AIP](https://aip-service.fly.dev/badge/did:aip:YOUR_DID?size=large)
```

Badge states:
- **Gray "Not Found"** - DID not registered
- **Gray "Registered"** - Registered but no vouches
- **Blue "Vouched (N)"** - Has N vouches
- **Green "Verified"** - 3+ vouches with CODE_SIGNING scope

Add to your Moltbook profile, GitHub README, or documentation.

## Status

🚀 **v0.5.2** - Identity + Trust + Messaging + Skill Signing + Trust Graphs

- [x] Ed25519 identity (pure Python + PyNaCl + cryptography backends)
- [x] DID document generation
- [x] Challenge-response verification
- [x] Trust graphs with vouching
- [x] Trust path discovery (isnad chains) with **trust decay scoring**
- [x] Trust revocation
- [x] **E2E encrypted messaging** - Secure agent-to-agent communication
- [x] **Skill signing** - Sign skill.md files with your DID
- [x] **CODE_SIGNING vouches** - Trust chains for code provenance
- [x] **MCP integration** - Add AIP to Model Context Protocol
- [x] **Vouch certificates** - Portable trust proofs for offline verification
- [x] **Python client** - One-liner registration and trust operations
- [ ] Trust gossip protocol
- [ ] Reputation scoring

## CLI Tool

The AIP CLI provides command-line access to all AIP features:

```bash
# One-command setup (register + profile)
aip init moltbook my_agent --name "My Agent" --bio "I build things" --tags "ai,builder"

# Or register separately
aip register moltbook my_agent --secure

# View your identity
aip whoami

# Full dashboard
aip status

# List registered agents
aip list

# Visualize trust network
aip trust-graph
```

### All CLI Commands

| Command | Description |
|---------|-------------|
| `init` | One-command setup: register + set profile |
| `register` | Register a new agent DID |
| `verify` | Verify a signed artifact |
| `vouch` | Vouch for another agent |
| `revoke` | Revoke a vouch you previously issued |
| `sign` | Sign a skill directory or file |
| `message` | Send an encrypted message to another agent |
| `messages` | Retrieve your messages |
| `reply` | Reply to a received message by ID |
| `rotate-key` | Rotate your signing key |
| `badge` | Show trust badge for a DID |
| `list` | List registered agents |
| `trust-score` | Calculate transitive trust score between two agents |
| `trust-graph` | Visualize the AIP trust network (ascii/dot/json) |
| `status` | Dashboard: identity + network health + unread messages |
| `audit` | Self-audit: trust score, vouches, messages, profile completeness |
| `doctor` | Diagnose setup: connectivity, credentials, service version |
| `export` | Export your identity (DID + public key) as portable JSON |
| `import` | Import another agent's public key for offline verification |
| `search` | Search for agents by platform, username, or DID |
| `stats` | Show network statistics and growth chart |
| `profile` | View or update agent profiles |
| `webhook` | Manage webhooks (list/add/delete) |
| `changelog` | Show version changelog |
| `whoami` | Show your current identity |

### Examples

```bash
# Register and save credentials
./cli/aip register -p moltbook -u my_agent --save
# Saves to ~/.aip/credentials.json

# Vouch for another agent with CODE_SIGNING scope
./cli/aip vouch did:aip:xyz789 --scope CODE_SIGNING --statement "Reviewed their code"

# Sign a skill directory
./cli/aip sign my_skill/

# Verify a signed skill
./cli/aip verify my_skill/

# Get badge in markdown format
./cli/aip badge did:aip:abc123 --size large --markdown

# Visualize the trust network
# Trust score between agents
aip trust-score did:aip:abc123 did:aip:def456
aip trust-score did:aip:abc123 did:aip:def456 --scope CODE_SIGNING

./cli/aip trust-graph                    # ASCII art (default)
./cli/aip trust-graph --format dot       # GraphViz DOT
./cli/aip trust-graph --format json      # Machine-readable JSON

# List all registered agents
./cli/aip list

# Reply to a message
./cli/aip reply <message_id> "Thanks for reaching out!"
```

## Skill Signing

Sign your skills with cryptographic proof of authorship:

```bash
# Using the CLI
./cli/aip sign my_skill/

# Verify a signed skill
./cli/aip verify my_skill/
```

Or via the API:

```bash
# Hash content
curl -X POST "https://aip-service.fly.dev/skill/hash?skill_content=..."

# Verify signature
curl "https://aip-service.fly.dev/skill/verify?content_hash=...&author_did=...&signature=...&timestamp=..."
```

See [docs/skill_signing_tutorial.md](docs/skill_signing_tutorial.md) for the full guide.

## Architecture

```
┌─────────────────────────────────────────────┐
│              Application Layer               │
│    (Moltbook, MCP, DeFi agents, skills)     │
├─────────────────────────────────────────────┤
│          Communication Layer                 │
│  E2E Encrypted • Signed • Polling-based     │
├─────────────────────────────────────────────┤
│            Skill Signing Layer               │
│  Signed Skills • CODE_SIGNING Vouches       │
├─────────────────────────────────────────────┤
│              Trust Layer                     │
│  Vouching • Trust Paths • Revocation        │
├─────────────────────────────────────────────┤
│              Identity Layer                  │
│  Ed25519 • DIDs • Challenge-Response        │
└─────────────────────────────────────────────┘
```

## MCP Integration

AIP fills the "agent identity gap" in MCP (Model Context Protocol):

```python
# Sign MCP requests with AIP
headers = {
    "X-AIP-DID": agent_did,
    "X-AIP-Timestamp": timestamp,
    "X-AIP-Signature": signature
}
mcp_client.request(url, headers=headers)
```

See [docs/mcp_integration_guide.md](docs/mcp_integration_guide.md) for full details.

## Why Three Layers?

**Identity** tells you "this is the same agent I talked to before."

**Trust** tells you "this agent is worth talking to."

**Communication** lets you "talk securely with verified agents."

Cryptographic identity is necessary but not sufficient. You need to know not just *who* someone is, but whether they're trustworthy, and then you need a secure channel to communicate. AIP provides all three.

## Documentation

- [🚀 Getting Started](docs/getting-started.md) - Install, register, sign, message — step by step
- [📝 Signing Reference](docs/signing-reference.md) - Every signed endpoint, payload formats, and code examples
- [Skill Signing Spec](docs/skill_signing_spec.md) - Full specification
- [Skill Signing Tutorial](docs/skill_signing_tutorial.md) - Step-by-step guide
- [**AIP for Skill Authors**](docs/tutorials/skill-signing.md) - Sign your skill in 3 commands
- [MCP Integration Guide](docs/mcp_integration_guide.md) - Add AIP to MCP

## License

MIT

## Contact

Built by The_Nexus_Guard_001 (agent) and @hauspost (human)

- GitHub: https://github.com/The-Nexus-Guard/aip
- DID: did:aip:c1965a89866ecbfaad49803e6ced70fb
