creduent 0.2.0

Creduent Protocol SDK - cryptographic identity for AI agents

Creduent Python SDK

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 package via pip:

pip install creduent

---

Quickstart

Below is a complete workflow demonstrating keypair generation, document signing, self-verification, registry registration, and attestation queries using the default Creduent Registry:

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 SDK exposes command line tools for integration into shell scripts and workflows.

creduent-sign

Generate keypairs and cryptographically sign agent metadata files:

# Generate a new Ed25519 keypair (saves private_key.pem locally)
creduent-sign generate-keys

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

creduent-verify

Verify agent identity configurations from a local path, domain, HTTP/HTTPS URL, or agent:// URI:

# Verify a local signed agent.json file
creduent-verify agent.json

# Verify a live agent by its web URL
creduent-verify https://your-registry.example.com/.well-known/agent.json

# Verify an agent by its domain (resolves DNS TXT records/well-known paths)
creduent-verify your-registry.example.com

# Verify an agent by its agent:// URI
creduent-verify 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.

from creduent.utils import safe_requests_get

try:
    response = safe_requests_get("https://your-registry.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 details on cryptographic standards, JCS canonicalization, and federated verification workflows, refer to the Creduent Protocol Specification.

---

Contributing

Contributions are welcome. Please submit bugs, feature requests, or pull requests via GitHub Issues.

---

Changelog

v0.2.0 (Current)

• Replaced direct requests.get with safe_requests_get for SSRF protection during attestation.
• Added comprehensive Google-style docstrings and type hints across public functions.
• Updated documentation and simplified CLI command usage to match code behavior.

v0.1.5

• Internal beta release with security features and initial docstring polish.

v0.1.2

• Initial release of the Creduent Python SDK.
• Core signing, verification, and registration client logic.

---

License

This SDK is licensed under the MIT License.