proveyouragent 0.1.0__tar.gz

proveyouragent-0.1.0/PKG-INFO

@@ -0,0 +1,327 @@
+Metadata-Version: 2.4
+Name: proveyouragent
+Version: 0.1.0
+Summary: Cryptographic identity and trust for AI agents
+License: MIT
+Keywords: ai,agents,identity,security,authentication,dpop,trust
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41.0
+Requires-Dist: pyjwt>=2.8
+Requires-Dist: fastapi>=0.100
+Requires-Dist: uvicorn>=0.23
+Requires-Dist: httpx>=0.24
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == "redis"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
+
+# agentid
+
+Cryptographic identity for AI agents.
+
+agentid gives each agent a keypair, a signed identity document, and a way to prove on every request that the request actually came from that agent. Services verify agent requests before processing them. Stolen tokens are useless without the private key.
+
+Built on Ed25519, OAuth 2.0 Dynamic Client Registration (RFC 7591), and DPoP (RFC 9449).
+
+---
+
+## The problem
+
+AI agents call APIs, read databases, write files, and send emails. Most do this with a hardcoded service account token or a borrowed user credential. There is no standard way for a service to know:
+
+- which agent made a request
+- who owns and is accountable for that agent
+- what the agent is actually allowed to do
+- whether the request was replayed from a stolen token
+
+agentid solves this with a small set of primitives that compose together.
+
+---
+
+## Install
+
+```bash
+pip install agentid
+```
+
+---
+
+## Quick start
+
+**Give your agent an identity:**
+
+```python
+from agentid import generate_keypair, save_keypair, create_software_statement
+
+key = generate_keypair()
+save_keypair(key)
+
+statement = create_software_statement(
+    private_key=key,
+    operator_domain="acme.com",
+    agent_name="billing-agent",
+    agent_version="1.0.0",
+    scopes=["invoices:read", "payments:write"],
+)
+```
+
+**Sign every request:**
+
+```python
+from agentid import create_dpop_proof
+
+proof = create_dpop_proof(key, method="GET", uri="https://api.acme.com/invoices")
+
+response = httpx.get(
+    "https://api.acme.com/invoices",
+    headers={
+        "X-Agent-Statement": statement,
+        "X-Agent-DPoP": proof,
+    }
+)
+```
+
+**Verify on the server:**
+
+```python
+from fastapi import FastAPI, Request
+from agentid.middleware import AgentIDMiddleware, verify_agent
+
+app = FastAPI()
+
+app.add_middleware(AgentIDMiddleware, get_public_key=my_key_resolver)
+
+@app.get("/invoices")
+def list_invoices(request: Request):
+    agent = verify_agent(request, required_scope="invoices:read")
+    return {"agent": agent.agent_name, "invoices": [...]}
+```
+
+---
+
+## How it works
+
+### Agent identity
+
+Every agent gets an Ed25519 keypair. The private key never leaves the agent. The public key is published at a well-known URL so any service can verify requests without calling home.
+
+The agent's identity document is a signed JWT called a software statement. It declares who owns the agent, what the agent is allowed to do, and where to find the public key.
+
+```python
+statement = create_software_statement(
+    private_key=key,
+    operator_domain="acme.com",       # who is accountable for this agent
+    agent_name="billing-agent",
+    agent_version="1.0.0",
+    scopes=["invoices:read"],
+    model="claude-sonnet-4-6",        # optional
+    prompt_hash="sha256:abc123",      # optional, for version tracking
+)
+```
+
+### Request signing with DPoP
+
+Bearer tokens can be stolen and replayed. DPoP (RFC 9449) binds each token to the agent's private key. Every request includes a fresh proof signed by the key, covering the HTTP method and URI. A stolen token is useless without the private key.
+
+```python
+# Create a fresh proof for each request
+proof = create_dpop_proof(
+    private_key=key,
+    method="GET",
+    uri="https://api.acme.com/invoices",
+)
+```
+
+### Verification
+
+The service checks four things on every request:
+
+1. The software statement signature is valid
+2. The software statement has not expired
+3. The agent has the required scope
+4. The DPoP proof is fresh, matches this request, and has not been used before
+
+```python
+from agentid import verify_agent_request, VerifiedAgent, VerificationError
+
+result = verify_agent_request(
+    software_statement=statement,
+    dpop_proof=proof,
+    method="GET",
+    uri="https://api.acme.com/invoices",
+    operator_public_key=public_key,
+    required_scope="invoices:read",
+)
+
+if isinstance(result, VerifiedAgent):
+    print(result.agent_name)     # billing-agent
+    print(result.operator_domain) # acme.com
+    print(result.scopes)         # ['invoices:read']
+```
+
+### FastAPI middleware
+
+The middleware handles verification automatically on every route. Verified agent details are attached to `request.state.agent`.
+
+```python
+from agentid.middleware import AgentIDMiddleware, verify_agent
+
+def get_public_key(operator_domain: str):
+    # Return the Ed25519PublicKey for this operator
+    # Fetch from your database, config, or key registry
+    return your_key_store.get(operator_domain)
+
+app.add_middleware(
+    AgentIDMiddleware,
+    get_public_key=get_public_key,
+    exclude_paths=["/health", "/docs"],  # skip verification on these
+)
+
+@app.get("/invoices")
+def list_invoices(request: Request):
+    agent = verify_agent(request, required_scope="invoices:read")
+    # agent.agent_name, agent.scopes, agent.operator_domain, etc.
+    return {"invoices": [...]}
+```
+
+### Delegation chains
+
+Orchestrator agents can delegate a subset of their permissions to sub-agents. The chain is cryptographically linked. Scopes can only shrink as they pass down the chain.
+
+```python
+from agentid.delegation import create_root_mandate, create_delegation, verify_delegation_chain
+
+# Human authorises orchestrator
+root = create_root_mandate(
+    private_key=operator_key,
+    operator_domain="acme.com",
+    human_principal="alice@acme.com",
+    scopes=["invoices:read", "payments:write"],
+    agent_id="acme.com/orchestrator",
+)
+
+# Orchestrator delegates a subset to sub-agent
+delegation = create_delegation(
+    delegator_key=orchestrator_key,
+    delegator_statement=orchestrator_statement,
+    delegate_agent_id="acme.com/summariser",
+    delegate_public_key_b64=summariser_pub_key,
+    scopes=["invoices:read"],    # subset of parent scopes only
+    parent_token=root,
+    human_principal="alice@acme.com",
+)
+
+# Tool verifies the full chain
+result = verify_delegation_chain(
+    token=delegation,
+    required_scope="invoices:read",
+    get_public_key=key_resolver,
+)
+
+print(result.human_principal)    # alice@acme.com
+print(result.delegate_agent_id)  # acme.com/summariser
+print(result.depth)              # 1
+```
+
+Scope escalation is rejected immediately:
+
+```python
+# This returns a DelegationError, not a token
+create_delegation(..., scopes=["invoices:read", "admin:delete"])
+# DelegationError: Cannot delegate scopes not present in parent token: {'admin:delete'}
+```
+
+---
+
+## Replay cache
+
+The default replay cache is in-memory. It works for single-process deployments but will not survive a restart or work across multiple processes.
+
+For production, use Redis:
+
+```python
+from agentid.cache import RedisCache
+from agentid.middleware import AgentIDMiddleware
+
+app.add_middleware(
+    AgentIDMiddleware,
+    get_public_key=get_public_key,
+    cache=RedisCache(url="redis://localhost:6379"),
+)
+```
+
+Or pass a cache directly to `verify_agent_request`:
+
+```python
+from agentid.cache import RedisCache
+
+cache = RedisCache(url="redis://localhost:6379")
+
+result = verify_agent_request(
+    ...,
+    cache=cache,
+)
+```
+
+---
+
+## What gets verified on every request
+
+| Check | What it catches |
+|---|---|
+| Software statement signature | Forged or tampered identity documents |
+| Statement expiry | Stale tokens |
+| Scope enforcement | Agents claiming permissions they were not granted |
+| DPoP proof signature | Requests not made by the key holder |
+| DPoP method and URI binding | Proofs reused on a different endpoint |
+| DPoP freshness | Old proofs being replayed |
+| DPoP jti uniqueness | Exact replay of a captured request |
+
+---
+
+## Running the examples
+
+```bash
+# Terminal 1: start the server
+uvicorn examples.server:app --reload
+
+# Terminal 2: run the client
+python examples/client.py
+```
+
+---
+
+## Running the tests
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## Design decisions
+
+**Ed25519 only.** No algorithm negotiation. Ed25519 is fast, has small keys, and has no known weaknesses. Supporting multiple algorithms adds complexity and attack surface.
+
+**No blockchain, no DID infrastructure.** DNS is the trust anchor. Operators publish their public key at a well-known URL on their domain. Every developer already knows how DNS works.
+
+**Errors as values, not exceptions.** `verify_agent_request` returns a `VerifiedAgent` or a `VerificationError`. No try/except needed in normal usage. The error always includes a human-readable reason.
+
+**Replay cache is pluggable.** The default in-memory cache works for development. Redis works for production. Any backend that implements `ReplayCache` works.
+
+---
+
+## License
+
+MIT

proveyouragent-0.1.0/README.md

@@ -0,0 +1,299 @@
+# agentid
+
+Cryptographic identity for AI agents.
+
+agentid gives each agent a keypair, a signed identity document, and a way to prove on every request that the request actually came from that agent. Services verify agent requests before processing them. Stolen tokens are useless without the private key.
+
+Built on Ed25519, OAuth 2.0 Dynamic Client Registration (RFC 7591), and DPoP (RFC 9449).
+
+---
+
+## The problem
+
+AI agents call APIs, read databases, write files, and send emails. Most do this with a hardcoded service account token or a borrowed user credential. There is no standard way for a service to know:
+
+- which agent made a request
+- who owns and is accountable for that agent
+- what the agent is actually allowed to do
+- whether the request was replayed from a stolen token
+
+agentid solves this with a small set of primitives that compose together.
+
+---
+
+## Install
+
+```bash
+pip install agentid
+```
+
+---
+
+## Quick start
+
+**Give your agent an identity:**
+
+```python
+from agentid import generate_keypair, save_keypair, create_software_statement
+
+key = generate_keypair()
+save_keypair(key)
+
+statement = create_software_statement(
+    private_key=key,
+    operator_domain="acme.com",
+    agent_name="billing-agent",
+    agent_version="1.0.0",
+    scopes=["invoices:read", "payments:write"],
+)
+```
+
+**Sign every request:**
+
+```python
+from agentid import create_dpop_proof
+
+proof = create_dpop_proof(key, method="GET", uri="https://api.acme.com/invoices")
+
+response = httpx.get(
+    "https://api.acme.com/invoices",
+    headers={
+        "X-Agent-Statement": statement,
+        "X-Agent-DPoP": proof,
+    }
+)
+```
+
+**Verify on the server:**
+
+```python
+from fastapi import FastAPI, Request
+from agentid.middleware import AgentIDMiddleware, verify_agent
+
+app = FastAPI()
+
+app.add_middleware(AgentIDMiddleware, get_public_key=my_key_resolver)
+
+@app.get("/invoices")
+def list_invoices(request: Request):
+    agent = verify_agent(request, required_scope="invoices:read")
+    return {"agent": agent.agent_name, "invoices": [...]}
+```
+
+---
+
+## How it works
+
+### Agent identity
+
+Every agent gets an Ed25519 keypair. The private key never leaves the agent. The public key is published at a well-known URL so any service can verify requests without calling home.
+
+The agent's identity document is a signed JWT called a software statement. It declares who owns the agent, what the agent is allowed to do, and where to find the public key.
+
+```python
+statement = create_software_statement(
+    private_key=key,
+    operator_domain="acme.com",       # who is accountable for this agent
+    agent_name="billing-agent",
+    agent_version="1.0.0",
+    scopes=["invoices:read"],
+    model="claude-sonnet-4-6",        # optional
+    prompt_hash="sha256:abc123",      # optional, for version tracking
+)
+```
+
+### Request signing with DPoP
+
+Bearer tokens can be stolen and replayed. DPoP (RFC 9449) binds each token to the agent's private key. Every request includes a fresh proof signed by the key, covering the HTTP method and URI. A stolen token is useless without the private key.
+
+```python
+# Create a fresh proof for each request
+proof = create_dpop_proof(
+    private_key=key,
+    method="GET",
+    uri="https://api.acme.com/invoices",
+)
+```
+
+### Verification
+
+The service checks four things on every request:
+
+1. The software statement signature is valid
+2. The software statement has not expired
+3. The agent has the required scope
+4. The DPoP proof is fresh, matches this request, and has not been used before
+
+```python
+from agentid import verify_agent_request, VerifiedAgent, VerificationError
+
+result = verify_agent_request(
+    software_statement=statement,
+    dpop_proof=proof,
+    method="GET",
+    uri="https://api.acme.com/invoices",
+    operator_public_key=public_key,
+    required_scope="invoices:read",
+)
+
+if isinstance(result, VerifiedAgent):
+    print(result.agent_name)     # billing-agent
+    print(result.operator_domain) # acme.com
+    print(result.scopes)         # ['invoices:read']
+```
+
+### FastAPI middleware
+
+The middleware handles verification automatically on every route. Verified agent details are attached to `request.state.agent`.
+
+```python
+from agentid.middleware import AgentIDMiddleware, verify_agent
+
+def get_public_key(operator_domain: str):
+    # Return the Ed25519PublicKey for this operator
+    # Fetch from your database, config, or key registry
+    return your_key_store.get(operator_domain)
+
+app.add_middleware(
+    AgentIDMiddleware,
+    get_public_key=get_public_key,
+    exclude_paths=["/health", "/docs"],  # skip verification on these
+)
+
+@app.get("/invoices")
+def list_invoices(request: Request):
+    agent = verify_agent(request, required_scope="invoices:read")
+    # agent.agent_name, agent.scopes, agent.operator_domain, etc.
+    return {"invoices": [...]}
+```
+
+### Delegation chains
+
+Orchestrator agents can delegate a subset of their permissions to sub-agents. The chain is cryptographically linked. Scopes can only shrink as they pass down the chain.
+
+```python
+from agentid.delegation import create_root_mandate, create_delegation, verify_delegation_chain
+
+# Human authorises orchestrator
+root = create_root_mandate(
+    private_key=operator_key,
+    operator_domain="acme.com",
+    human_principal="alice@acme.com",
+    scopes=["invoices:read", "payments:write"],
+    agent_id="acme.com/orchestrator",
+)
+
+# Orchestrator delegates a subset to sub-agent
+delegation = create_delegation(
+    delegator_key=orchestrator_key,
+    delegator_statement=orchestrator_statement,
+    delegate_agent_id="acme.com/summariser",
+    delegate_public_key_b64=summariser_pub_key,
+    scopes=["invoices:read"],    # subset of parent scopes only
+    parent_token=root,
+    human_principal="alice@acme.com",
+)
+
+# Tool verifies the full chain
+result = verify_delegation_chain(
+    token=delegation,
+    required_scope="invoices:read",
+    get_public_key=key_resolver,
+)
+
+print(result.human_principal)    # alice@acme.com
+print(result.delegate_agent_id)  # acme.com/summariser
+print(result.depth)              # 1
+```
+
+Scope escalation is rejected immediately:
+
+```python
+# This returns a DelegationError, not a token
+create_delegation(..., scopes=["invoices:read", "admin:delete"])
+# DelegationError: Cannot delegate scopes not present in parent token: {'admin:delete'}
+```
+
+---
+
+## Replay cache
+
+The default replay cache is in-memory. It works for single-process deployments but will not survive a restart or work across multiple processes.
+
+For production, use Redis:
+
+```python
+from agentid.cache import RedisCache
+from agentid.middleware import AgentIDMiddleware
+
+app.add_middleware(
+    AgentIDMiddleware,
+    get_public_key=get_public_key,
+    cache=RedisCache(url="redis://localhost:6379"),
+)
+```
+
+Or pass a cache directly to `verify_agent_request`:
+
+```python
+from agentid.cache import RedisCache
+
+cache = RedisCache(url="redis://localhost:6379")
+
+result = verify_agent_request(
+    ...,
+    cache=cache,
+)
+```
+
+---
+
+## What gets verified on every request
+
+| Check | What it catches |
+|---|---|
+| Software statement signature | Forged or tampered identity documents |
+| Statement expiry | Stale tokens |
+| Scope enforcement | Agents claiming permissions they were not granted |
+| DPoP proof signature | Requests not made by the key holder |
+| DPoP method and URI binding | Proofs reused on a different endpoint |
+| DPoP freshness | Old proofs being replayed |
+| DPoP jti uniqueness | Exact replay of a captured request |
+
+---
+
+## Running the examples
+
+```bash
+# Terminal 1: start the server
+uvicorn examples.server:app --reload
+
+# Terminal 2: run the client
+python examples/client.py
+```
+
+---
+
+## Running the tests
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## Design decisions
+
+**Ed25519 only.** No algorithm negotiation. Ed25519 is fast, has small keys, and has no known weaknesses. Supporting multiple algorithms adds complexity and attack surface.
+
+**No blockchain, no DID infrastructure.** DNS is the trust anchor. Operators publish their public key at a well-known URL on their domain. Every developer already knows how DNS works.
+
+**Errors as values, not exceptions.** `verify_agent_request` returns a `VerifiedAgent` or a `VerificationError`. No try/except needed in normal usage. The error always includes a human-readable reason.
+
+**Replay cache is pluggable.** The default in-memory cache works for development. Redis works for production. Any backend that implements `ReplayCache` works.
+
+---
+
+## License
+
+MIT

proveyouragent-0.1.0/proveyouragent/__init__.py

@@ -0,0 +1,17 @@
+from proveyouragent.keypair import generate_keypair, save_keypair, load_keypair
+from proveyouragent.identity import create_software_statement, decode_software_statement
+from proveyouragent.dpop import create_dpop_proof
+from proveyouragent.verify import verify_agent_request, VerifiedAgent, VerificationError
+
+__version__ = "0.1.0"
+__all__ = [
+    "generate_keypair",
+    "save_keypair",
+    "load_keypair",
+    "create_software_statement",
+    "decode_software_statement",
+    "create_dpop_proof",
+    "verify_agent_request",
+    "VerifiedAgent",
+    "VerificationError",
+]