Metadata-Version: 2.4
Name: creduent
Version: 0.1.5
Summary: Creduent Protocol SDK - cryptographic identity for AI agents
Home-page: https://github.com/creduent/creduent
Author: Creduent Foundation
License: MIT
Project-URL: Homepage, https://github.com/creduent/creduent
Project-URL: Repository, https://github.com/creduent/creduent-python
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography
Requires-Dist: requests
Requires-Dist: jcs
Requires-Dist: fastapi
Dynamic: home-page
Dynamic: license-file

# Creduent Python SDK

[![PyPI version](https://img.shields.io/pypi/v/creduent.svg?color=blue)](https://pypi.org/project/creduent/)
[![License](https://img.shields.io/github/license/creduent/creduent.svg)](https://github.com/creduent/creduent-python/blob/main/LICENSE)
[![Python Compatibility](https://img.shields.io/pypi/pyversions/creduent.svg)](https://pypi.org/project/creduent/)
[![Downloads](https://pepy.tech/badge/creduent)](https://pepy.tech/project/creduent)

The official Python SDK for the **Creduent Protocol** - a federated, open trust-verification layer and cryptographic identity infrastructure for autonomous AI agents.

Creduent enables autonomous agents to cryptographically sign metadata, verify identities across administrative domains via DNS bindings, and interact with the Creduent registry for secure, machine-to-machine trust checks.

---

## Key Features

- 🔑 **Cryptographic Identity Management**: Generate secure Ed25519 keypairs for AI agents.
- ✍️ **RFC 8785 Canonical Signatures**: Compute cryptographic signatures over JSON agent documents using RFC 8785 JSON Canonicalization Scheme (JCS) and Ed25519.
- 🛡️ **SSRF Protection**: Safe endpoint resolution and verification using custom requests wrappers that block access to private, loopback, and local network ranges.
- 🔗 **DNS Trust Binding**: Resolve and verify cryptographic bindings between agent identifiers (`agent://`) and Web domains.
- 🏛️ **Registry Integration**: Seamless interaction with the Creduent Registry to register agents and resolve active signed attestations.
- 🛠️ **CLI Utilities**: Out-of-the-box CLI commands for signing, verification, and key generation.
- ⚙️ **Automatic Environment Loader**: Integrated environment loader utility specifically optimized to avoid local dot-env interference in production serverless environments like Vercel.

---

## Architectural Flow

```
+------------------+             +----------------------+             +------------------+
|   Agent Domain   |             |   Creduent Registry  |             |   Agent Client   |
|   (agent.json)   |             |                      |             |    (MCP Host)    |
+------------------+             +----------------------+             +------------------+
         |                                |                                |
         |---- 1. Serve agent.json ------>|                                |
         |                                |-- 2. Verify identity & DNS --->|
         |                                |      and sign attestation      |
         |                                |                                |
         |<--- 3. Query agent endpoint ------------------------------------|  (verify_agent tool)
         |                                |                                |
         |                                |<--- 4. Fetch attestation ------|  (registry validation)
```

---

## Installation

Install the self-contained package from PyPI:

```bash
pip install creduent
```

---

## Quickstart

Here is how to generate a keypair, sign a draft agent identity, verify it, and query the registry:

```python
import os
from creduent import (
    generate_keys,
    sign,
    verify,
    register,
    attest,
    CreduEntError
)

# Optional: Set the Creduent registry endpoint (defaults to https://api.idevsec.com)
os.environ["CREDUENT_REGISTRY_URL"] = "https://api.idevsec.com"

try:
    # 1. Generate a new Ed25519 keypair
    private_key_pem, public_key_str = generate_keys()
    print(f"[+] Generated Public Key: {public_key_str}\n")

    # 2. Sign a draft agent.json document
    draft_document = {
        "version": "1.0",
        "agent_id": "agent://creduent/reconbot",
        "owner": "Creduent Foundation",
        "public_key": public_key_str,
        "endpoint": "https://api.idevsec.com/recon",
        "capabilities": ["osint", "dns_lookup", "vulnerability_scan"]
    }
    
    # Compute signature and attach to the document
    signed_doc = sign(draft_document, private_key_pem)
    print("[+] Signed agent.json:")
    print(signed_doc)
    print()

    # 3. Verify a self-signed agent.json (from dict, URL, domain, or agent:// URI)
    result = verify(signed_doc)
    print(f"[+] Self-Signed Verification Result (dict): {result.valid}")
    
    # 4. Register the agent with the Creduent registry
    reg_result = register(
        agent_id="agent://creduent/reconbot",
        domain="api.idevsec.com",
        agent_json_url="https://api.idevsec.com/.well-known/agent.json"
    )
    print(f"[+] Registration Successful: {reg_result.success}")
    if reg_result.attestation:
        print(f"[+] Attestation Level: {reg_result.attestation.get('level')}\n")

    # 5. Fetch and validate an active attestation for an agent
    attest_result = attest("agent://creduent/reconbot")
    print(f"[+] Is Attested: {attest_result.attested}")
    print(f"[+] Attestation Level: {attest_result.level}")
    print(f"[+] Issued At: {attest_result.issued_at}")
    print(f"[+] Expires At: {attest_result.expires_at}\n")

except CreduEntError as e:
    print(f"[-] Creduent Protocol Error: {e}")
```

---

## Command Line Interface (CLI)

The package installs console command entrypoints for CLI usage.

### `creduent-sign`
Manage keypairs and sign agent identity documents:
```bash
# Generate a new Ed25519 keypair
creduent-sign generate-keys --private-out private_key.pem --public-out public_key.txt

# Sign a draft agent.json document
creduent-sign sign --key private_key.pem --input draft_agent.json --output agent.json
```

### `creduent-verify`
Verify agent identities on the fly:
```bash
# Verify a local signed agent.json file
creduent-verify file --path agent.json

# Verify a live agent by its web URL
creduent-verify url --url https://api.idevsec.com/.well-known/agent.json

# Verify an agent by its domain (resolves DNS TXT records first)
creduent-verify domain --name api.idevsec.com

# Verify an agent by its agent:// URI
creduent-verify agent-id --uri agent://creduent/reconbot
```

---

## Advanced Utilities

### SSRF Protection
The SDK provides a security utility `safe_requests_get` to perform HTTP operations on agent endpoints. It resolves hostname IP addresses prior to connecting, and blocks access to private, loopback, and local network ranges (RFC 1918 / RFC 4193) to protect against server-side request forgery.

```python
from creduent.utils import safe_requests_get

try:
    response = safe_requests_get("https://api.example.com/.well-known/agent.json", timeout=5)
    print("Agent payload fetched securely.")
except Exception as e:
    print(f"Fetch blocked or failed: {e}")
```

### Serverless Environment Loader
The SDK contains `load_dotenv` which manually discovers and parses `.env.local` or `.env` files in local workspaces but automatically skips loading them in Vercel environment targets (where `VERCEL=1` is set). This prevents local development environment settings from overriding production environment variables.

---

## Protocol Specification

For full information on the cryptographic standards, JCS canonicalization, and the federated verification workflows, read the complete [Creduent Protocol Specification](https://github.com/creduent/creduent).

## License

This SDK is licensed under the [MIT License](LICENSE).
