ai-agent-passport 0.2.1

Signed identity and policy checks for AI agents.

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

python examples/gateway_demo/run_demo.py

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:

pip install ai-agent-passport

From source:

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

For development:

pip install -e ".[dev]"
pytest

Quickstart

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:

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:

agent-passport verify agent-passport.json

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

Second, an allowed action passes local policy:

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

PASS: action 'send_message' is allowed by local policy

Third, a forbidden action is blocked:

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

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

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

CRITICAL: cryptographic signature invalid - payload may be tampered

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

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:

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

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

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

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.

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:

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:

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.