Metadata-Version: 2.4
Name: ai-agent-passport
Version: 0.2.1
Summary: Signed identity and policy checks for AI agents.
Author: Alexander Manev
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42.0.0
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# agent-passport

Signed identity and policy checks for AI agents.

`agent-passport` is a local-first CLI for creating, signing, verifying, and policy-checking machine-readable agent identity documents.

**Status:** early prototype. The core signing, verification, schema validation, and policy-checking flow works; protocol integrations are experimental examples.

An agent passport gives agents, tools, gateways, and humans a simple way to answer:

- Who claims to operate this agent?
- What capabilities and permissions does it declare?
- Has the identity document been tampered with?
- Is this requested action allowed by my local policy?

The project is intentionally small: a practical trust primitive for the moment before one system decides whether to interact with an agent.

## 30-Second Demo

```bash
python examples/gateway_demo/run_demo.py
```

```text
agent-passport gateway demo
===========================

Scenario: valid passport requests allowed action
[PASS] verified agent: Demo Landlord Agent
[PASS] action allowed: send_message

Scenario: valid passport requests forbidden action
[PASS] verified agent: Demo Landlord Agent
[BLOCKED] passport does not declare permission for action 'write_file'

Scenario: tampered passport requests allowed action
[BLOCKED] passport digest invalid - payload may be tampered

Scenario: untrusted operator requests allowed action
[PASS] verified agent: Unknown Operator Agent
[BLOCKED] operator 'unknown.example' is not trusted by local policy
```

## Current Scope

This version is a local developer CLI and Python library:

- generate an Ed25519 keypair
- inspect and rotate local signing keys
- scaffold a human-editable `agent.yaml`
- sign claims into a canonical `agent-passport.json`
- verify that a passport has not been tampered with
- reject malformed manifests with clear validation errors
- inspect signed claims
- print a stable passport fingerprint for logs and reviews
- evaluate an intended action against local deny-by-default policy
- demonstrate where the trust gate can sit in a gateway or MCP-style proxy

## Trust Model

An agent passport proves who signed a set of claims. Those claims can include the agent's operator, model, runtime, capabilities, permissions, and expiry.

Some claims are self-declared until backed by stronger attestations. For example, a `model_claim` says what the signer claims the agent uses; it is not, by itself, cryptographic proof of the underlying model.

## Install

From PyPI:

```bash
pip install ai-agent-passport
```

From source:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

For development:

```bash
pip install -e ".[dev]"
pytest
```

## Quickstart

```bash
agent-passport init
agent-passport key inspect .agent-passport/public.jwk
agent-passport issue --out agent.yaml
agent-passport sign agent.yaml --out agent-passport.json
agent-passport verify agent-passport.json --public-key .agent-passport/public.jwk
agent-passport fingerprint agent-passport.json
agent-passport inspect agent-passport.json
agent-passport policy-check agent-passport.json examples/policy.yaml --action send_message
```

Try a blocked action:

```bash
agent-passport policy-check agent-passport.json examples/policy.yaml --action write_file --resource ~/.ssh/id_rsa
```

## Demo

The MVP is designed around three simple trust decisions.

First, a valid passport verifies:

```bash
agent-passport verify agent-passport.json
```

```text
PASS: signature valid for Local Demo Agent (agent:demo:local)
```

Second, an allowed action passes local policy:

```bash
agent-passport policy-check agent-passport.json examples/policy.yaml --action send_message
```

```text
PASS: action 'send_message' is allowed by local policy
```

Third, a forbidden action is blocked:

```bash
agent-passport policy-check agent-passport.json examples/policy.yaml --action write_file --resource ~/.ssh/id_rsa
```

```text
BLOCKED: passport does not declare permission for action 'write_file'
```

If a signed passport is edited after signing, verification fails:

```text
CRITICAL: cryptographic signature invalid - payload may be tampered
```

You can also print a stable SHA-256 fingerprint of the signed canonical payload:

```bash
agent-passport fingerprint agent-passport.json
```

This is useful for audit logs, reviews, and future registries.

## Example Fixtures

The repository includes signed fixtures for demos:

```bash
agent-passport verify examples/fixtures/valid/passport.json \
  --public-key examples/fixtures/keys/public.jwk
```

```bash
agent-passport verify examples/fixtures/tampered/passport.json \
  --public-key examples/fixtures/keys/public.jwk
```

```bash
agent-passport verify examples/fixtures/expired/passport.json \
  --public-key examples/fixtures/keys/public.jwk
```

```bash
agent-passport policy-check examples/fixtures/untrusted-operator/passport.json \
  examples/policy.yaml \
  --public-key examples/fixtures/keys/public.jwk \
  --action send_message
```

## Gateway Demo

The gateway demo simulates a runtime receiving agent passports and requested actions, then allowing or blocking each request through signature verification and local policy.

```bash
python examples/gateway_demo/run_demo.py
```

## MCP-Style Proxy Demo

The MCP-style proxy demo shows the same trust gate at a JSON-RPC `tools/call` boundary:

```bash
python examples/mcp_proxy_demo/run_demo.py
```

It launches a toy MCP-like server behind a proxy. The proxy forwards allowed tool calls and returns JSON-RPC errors for blocked calls.

## Schemas

The project ships JSON Schemas for the core document types:

- `schemas/agent-claims.schema.json`
- `schemas/agent-passport.schema.json`
- `schemas/policy.schema.json`

Runtime validation uses the packaged copies of these schemas.

## Python API

The CLI wraps a small Python API:

```python
from pathlib import Path

from agent_passport import verify_passport_file, policy_check_file

claims = verify_passport_file(
    Path("agent-passport.json"),
    Path(".agent-passport/public.jwk"),
)

decision = policy_check_file(
    Path("agent-passport.json"),
    Path("policy.yaml"),
    "send_message",
    None,
    Path(".agent-passport/public.jwk"),
)
```

## Security

See `docs/architecture.md`, `THREAT_MODEL.md`, and `SECURITY.md` for the current architecture, trust assumptions, protected cases, and non-goals.

## Publishing

The package is ready to build locally, but not yet published to PyPI. See `docs/publishing.md` for the TestPyPI/PyPI checklist.

## Non-goals for the first version

- full DID or Verifiable Credentials support
- proving which model an agent is actually running
- hosted verification service
- production MCP/A2A integration
- enterprise identity governance

These are natural future directions once the local signing and policy primitive is solid.
