creduent 0.1.5

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 self-contained package from PyPI:

pip install creduent

---

Quickstart

Here is how to generate a keypair, sign a draft agent identity, verify it, and query the 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 package installs console command entrypoints for CLI usage.

creduent-sign

Manage keypairs and sign agent identity documents:

# 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:

# 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.

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.

License

This SDK is licensed under the MIT License.