Metadata-Version: 2.4
Name: agentcert
Version: 0.2.0
Summary: Bitcoin-anchored identity certificates for AI agents
Author: Shaleen Chauhan
License-Expression: MIT
Project-URL: Homepage, https://github.com/shaleenchauhan/agentcert
Project-URL: Documentation, https://github.com/shaleenchauhan/agentcert#readme
Project-URL: Repository, https://github.com/shaleenchauhan/agentcert
Project-URL: Issues, https://github.com/shaleenchauhan/agentcert/issues
Keywords: bitcoin,ai,identity,certificates,agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42.0
Requires-Dist: requests>=2.31
Requires-Dist: click>=8.1
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: responses>=0.24; extra == "dev"
Dynamic: license-file

# AgentCert

Bitcoin-anchored identity certificates for AI agents.

AgentCert is the open-source Python implementation of **AIT-1** (Agent Identity Certificates) from the Agent Internet Trust protocol. It lets developers create cryptographically signed, Bitcoin-anchored identity certificates that bind a **creator** (human or company) to an **agent** (autonomous software) — with verifiable metadata, capabilities, constraints, and a risk tier.

Every certificate is signed with ECDSA/secp256k1, hashed with SHA-256, and optionally anchored to Bitcoin via OP_RETURN. Any third party can verify the certificate using only math and the blockchain.

**Proven on Bitcoin testnet:** [`6b3b8cd6...`](https://blockstream.info/testnet/tx/6b3b8cd6624d833e98add57823a7a8ba72134a9de4aae6b7eb7617ebd7cb771c)

## Install

```bash
pip install agentcert
```

Or from source:

```bash
git clone https://github.com/shaleenchauhan/agentcert.git
cd agentcert
pip install -e ".[dev]"
```

Requires Python 3.11+. Dependencies: `cryptography`, `requests`, `click`.

For LangChain integration:

```bash
pip install agentcert[langchain]
```

## Quickstart

```python
import agentcert

# Generate key pairs
creator_keys = agentcert.generate_keys()
agent_keys = agentcert.generate_keys()

# Create a signed certificate
cert = agentcert.create_certificate(
    creator_keys=creator_keys,
    agent_keys=agent_keys,
    name="procurement-agent-v1",
    platform="langchain",
    model_hash="sha256:a1b2c3d4e5f6",
    capabilities=["procurement", "negotiation"],
    constraints=["max-transaction-50000-usd"],
    risk_tier=3,
    expires_days=90,
)

# Verify it
result = agentcert.verify(cert)
assert result.valid
print(result.status)  # "VALID"

# Save to disk
agentcert.save_certificate(cert, "agent.cert.json")
agentcert.save_keys(creator_keys, "creator.keys.json")
```

## CLI

AgentCert ships a full command-line interface:

```bash
# Generate keys
agentcert keygen -o creator.keys.json
agentcert keygen -o agent.keys.json

# Create a certificate
agentcert create \
  --creator-keys creator.keys.json \
  --agent-keys agent.keys.json \
  --name "my-agent" \
  --platform "langchain" \
  --capabilities "procurement,negotiation" \
  --constraints "max-50k-usd" \
  --risk-tier 3 \
  --expires 90d \
  -o cert.json

# Inspect it
agentcert inspect cert.json

# Verify it
agentcert verify cert.json

# Update (add capabilities, new version in the chain)
agentcert update cert.json \
  --creator-keys creator.keys.json \
  --add-capability "invoicing" \
  -o cert-v2.json

# Revoke
agentcert revoke cert-v2.json \
  --creator-keys creator.keys.json \
  --reason "Decommissioned" \
  -o revoke.json

# Verify the full chain
agentcert verify-chain cert.json cert-v2.json revoke.json

# --- Audit Trail ---

# Create an audit trail bound to a certificate
agentcert audit create cert.json --agent-keys agent.keys.json -o trail.json

# Log actions
agentcert audit log trail.json --agent-keys agent.keys.json \
  --action-type API_CALL --summary "Called weather API" \
  --detail '{"url": "https://api.weather.com", "status": 200}'

agentcert audit log trail.json --agent-keys agent.keys.json \
  --action-type DECISION --summary "Selected cheapest vendor"

agentcert audit log trail.json --agent-keys agent.keys.json \
  --action-type TRANSACTION --summary "Placed order for 42 widgets" \
  --detail '{"vendor": "Acme", "amount": 42.0}'

# Verify the trail (with optional certificate binding)
agentcert audit verify trail.json --cert cert.json

# Inspect the trail
agentcert audit inspect trail.json --entries
```

## SDK API

All functions are available at the top level — no submodule imports needed.

### Keys

```python
creator_keys = agentcert.generate_keys()
agentcert.save_keys(creator_keys, "creator.keys.json")
creator_keys = agentcert.load_keys("creator.keys.json")

# Derive Bitcoin address (for funding anchor transactions)
address = agentcert.derive_bitcoin_address(creator_keys, network="testnet")
```

### Certificates

```python
cert = agentcert.create_certificate(
    creator_keys=creator_keys,
    agent_keys=agent_keys,
    name="my-agent",
    platform="langchain",
    model_hash="sha256:...",
    capabilities=["task-a", "task-b"],
    constraints=["spending-limit-1000"],
    risk_tier=2,
    expires_days=90,
)

agentcert.save_certificate(cert, "agent.cert.json")
cert = agentcert.load_certificate("agent.cert.json")
```

### Verification

The verifier runs 6 checks (all must pass for `VALID`):

1. **cert_id integrity** — SHA-256(body) matches cert_id
2. **creator_id derivation** — SHA-256(creator_public_key) matches creator_id
3. **agent_id derivation** — SHA-256(agent_public_key) matches agent_id
4. **Creator signature** — ECDSA verification against creator_public_key
5. **Anchor integrity** — certificate hash matches the anchored hash (if receipt provided)
6. **Expiration** — current time < expires

```python
result = agentcert.verify(cert)                # without anchor
result = agentcert.verify(cert, receipt)        # with anchor receipt

print(result.status)  # "VALID" or "INVALID"
print(result.valid)   # True / False

for check in result.checks:
    print(f"[{'PASS' if check.passed else 'FAIL'}] {check.name}: {check.detail}")
```

### Chain Operations

Certificates form a linked chain: create &rarr; update &rarr; ... &rarr; revoke.

```python
# Update (carries over unchanged fields)
updated = agentcert.update_certificate(
    previous_cert=cert,
    creator_keys=creator_keys,
    capabilities=["procurement", "negotiation", "invoicing"],
)

# Revoke (terminates the chain)
revocation = agentcert.revoke_certificate(
    previous_cert=updated,
    creator_keys=creator_keys,
    reason="Decommissioned",
)

# Verify the full chain
chain_result = agentcert.verify_chain([cert, updated, revocation])
print(chain_result.status)  # "REVOKED"
print(chain_result.valid)   # True (REVOKED is a valid terminal state)
```

### Audit Trail

Create a tamper-evident log of every action an agent takes, cryptographically signed and hash-chained:

```python
# Create an audit trail bound to a certificate
trail = agentcert.create_audit_trail(cert, agent_keys)

# Log actions (each entry is signed by the agent and chained to the previous)
agentcert.log_action(
    trail, agent_keys,
    action_type=agentcert.ActionType.API_CALL,
    action_summary="Queried vendor pricing API",
    action_detail={"url": "https://api.vendors.example/prices", "status": 200},
)

agentcert.log_action(
    trail, agent_keys,
    action_type=agentcert.ActionType.DECISION,
    action_summary="Selected cheapest vendor: Acme Corp",
)

agentcert.log_action(
    trail, agent_keys,
    action_type=agentcert.ActionType.TRANSACTION,
    action_summary="Placed purchase order for 500 widgets",
    action_detail={"vendor": "Acme Corp", "quantity": 500, "total": 6250.00},
)

# Verify the full trail (11 checks)
result = agentcert.verify_audit_trail(trail, cert)
print(result.status)  # "VALID"

# Verify a single entry (6 checks)
entry_result = agentcert.verify_audit_entry(trail.entries[0], cert)

# Inspect
info = agentcert.get_trail_info(trail)
print(info.entry_count)  # 3

# Filter entries
api_calls = agentcert.get_trail_entries(trail, action_type=agentcert.ActionType.API_CALL)
recent = agentcert.get_trail_entries(trail, start=1, end=2)

# Save / Load
agentcert.save_trail(trail, "trail.json")
trail = agentcert.load_trail("trail.json")
```

Action types: `API_CALL`, `TOOL_USE`, `DECISION`, `DATA_ACCESS`, `TRANSACTION`, `COMMUNICATION`, `ERROR`, `CUSTOM`.

Entry verification runs 6 checks: entry_id integrity, agent_id derivation, agent signature, sequence validity, timestamp validity, and certificate binding.

Trail verification runs 11 checks: non-empty trail, trail_id/cert_id/agent consistency, first-entry linkage, hash-chain integrity, sequence continuity, timestamp ordering, all entry IDs, all signatures, and certificate binding.

### LangChain Integration

Add identity certificates and signed audit trails to any LangChain agent with a few lines of code. The middleware automatically captures all LLM calls, tool invocations, and agent decisions as signed audit entries.

```python
from agentcert.integrations.langchain import AgentCertMiddleware

# Create middleware (generates certificate + audit trail)
middleware = AgentCertMiddleware(
    creator_keys="creator.keys.json",    # path or KeyPair
    agent_keys="agent.keys.json",        # path or KeyPair
    agent_name="procurement-agent-v1",
    capabilities=["procurement", "negotiation"],
    constraints=["max-transaction-50000-usd"],
    risk_tier=3,
)

# Wrap your executor — all actions are logged automatically
executor = middleware.wrap(executor)
result = executor.invoke({"input": "Find the cheapest supplier"})

# Verify the audit trail (11 checks)
verification = middleware.verify()
print(verification.status)  # "VALID"

# Inspect entries
for entry in middleware.get_entries():
    print(f"[{entry.sequence}] {entry.action_summary}")

# Filter by type
tools = middleware.get_entries(action_type=agentcert.ActionType.TOOL_USE)

# Save everything (certificate + trail)
middleware.save("./agent-audit/")

# Reload and continue logging
loaded = AgentCertMiddleware.load("./agent-audit/", agent_keys="agent.keys.json")
```

For more control, use the callback handler directly:

```python
from agentcert.integrations.langchain import AgentCertCallbackHandler

handler = AgentCertCallbackHandler(trail, agent_keys)
result = executor.invoke({"input": "..."}, config={"callbacks": [handler]})
```

**Privacy:** LLM prompts, responses, and tool outputs are stored as SHA-256 hashes only — the trail proves what happened without exposing raw data.

**Log levels:** `"minimal"` (tools + decisions only), `"standard"` (default — adds LLM calls), `"verbose"` (adds chain events).

### Bitcoin Anchoring

Anchor a certificate to Bitcoin via an OP_RETURN transaction:

```python
# The creator's Bitcoin address must be funded first
address = agentcert.derive_bitcoin_address(creator_keys, network="testnet")
print(f"Fund this address: {address}")

# Anchor (builds, signs, and broadcasts a Bitcoin transaction)
receipt = agentcert.anchor(cert, creator_keys=creator_keys, network="testnet")
print(receipt.txid)

# Save the receipt for later verification
agentcert.save_receipt(receipt, "receipt.json")
receipt = agentcert.load_receipt("receipt.json")
```

The OP_RETURN payload is 38 bytes:

```
[AIT\0]   protocol tag     (4 bytes)
[0x01]    version           (1 byte)
[0x02]    IDENTITY_CERT     (1 byte)
[...]     SHA-256 hash      (32 bytes)
```

## Certificate Structure

```json
{
  "ait_version": 1,
  "cert_type": 1,
  "cert_id": "<SHA-256 of body>",
  "timestamp": 1739750000,
  "expires": 1747526000,
  "agent_public_key": "<33-byte compressed public key, hex>",
  "agent_id": "<SHA-256 of agent_public_key>",
  "creator_public_key": "<33-byte compressed public key, hex>",
  "creator_id": "<SHA-256 of creator_public_key>",
  "agent_metadata": {
    "name": "my-agent",
    "model_hash": "sha256:...",
    "platform": "langchain",
    "capabilities": ["procurement", "negotiation"],
    "constraints": ["max-transaction-50000-usd"],
    "risk_tier": 3
  },
  "previous_cert_id": null,
  "creator_signature": "<ECDSA DER signature, hex>"
}
```

| Field | Description |
|-------|-------------|
| `cert_type` | 1 = CREATION, 2 = UPDATE, 3 = REVOCATION |
| `cert_id` | SHA-256 of the certificate body (all fields except `cert_id` and `creator_signature`) |
| `creator_signature` | ECDSA/secp256k1 signature over the same body |
| `previous_cert_id` | Links to the prior certificate in the chain (null for the first) |

## How It Works

**Signing:** The cert_id and creator_signature are computed over the same canonical JSON body. The cert_id verifies integrity (any tampering changes the hash). The signature verifies authenticity (only the creator's private key can produce it). Both are independently checkable by any third party.

**Anchoring:** The anchor hash is SHA-256 of the *complete* certificate (including cert_id and signature). This goes into a Bitcoin OP_RETURN output. If anything is modified after anchoring, the anchor check fails.

**Chain verification** checks: each cert's `previous_cert_id` links to the prior cert's `cert_id`, the same creator throughout, valid signatures on every cert, and the final cert's type determines the chain status (ACTIVE or REVOKED).

For the full protocol design, threat model, and technical specification, see the [Research](#research) section.

## Development

```bash
git clone https://github.com/shaleenchauhan/agentcert.git
cd agentcert
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,langchain]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=agentcert --cov-report=term-missing

# Run examples
python examples/quickstart.py
python examples/full_lifecycle.py
python examples/audit_trail_demo.py
python examples/langchain_demo.py
```

## Project Structure

```
agentcert/
  src/agentcert/
    __init__.py          # Public API (51 exports, no submodule imports needed)
    keys.py              # Key generation, save, load (secp256k1)
    certificate.py       # Certificate creation, signing, serialization
    chain.py             # Update, revoke, chain verification
    anchor.py            # Bitcoin OP_RETURN + Blockstream API
    verify.py            # 6-check certificate verification
    audit.py             # Audit trail creation, logging, persistence
    audit_verify.py      # 6-check entry + 11-check trail verification
    integrations/
      langchain.py       # AgentCertCallbackHandler + AgentCertMiddleware
    types.py             # KeyPair, Certificate, AuditEntry, ActionType, etc.
    exceptions.py        # Custom exception hierarchy
    cli.py               # Click-based CLI (12 commands)
  tests/                 # 258 tests
  examples/              # quickstart.py, full_lifecycle.py, audit_trail_demo.py, langchain_demo.py
  papers/                # Whitepaper, technical spec, condensed overview
```

## Technical Decisions

| Component | Choice | Rationale |
|-----------|--------|-----------|
| Language | Python 3.11+ | AI/ML ecosystem standard |
| Curve | secp256k1 | Bitcoin-native, same keys for signing and anchoring |
| Signatures | ECDSA | Proven; Schnorr migration path later |
| Hashing | SHA-256 | Bitcoin-native |
| Serialization | JSON (deterministic) | `sort_keys=True, separators=(',',':')` |
| CLI | Click | Mature, clean subcommand support |
| Bitcoin API | Blockstream | No auth, free, reliable |
| Dependencies | 3 runtime | `cryptography`, `requests`, `click` |

## Research

AgentCert implements AIT-1 from the Agent Internet Trust protocol. The research papers cover the full protocol design, adversarial analysis, and technical specification:

- [**Whitepaper**](papers/whitepaper.pdf) — Protocol motivation, architecture, trust model, and threat analysis
- [**Condensed Overview**](papers/condensed.pdf) — Shorter summary of the protocol and its design rationale
- [**Technical Specification**](papers/technical-spec.pdf) — Formal specification of certificate structure, signing, anchoring, and verification

## License

MIT
