agentguard-python-sdk 0.2.5__tar.gz → 0.2.7__tar.gz

agentguard_python_sdk-0.2.7/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: agentguard-python-sdk
+Version: 0.2.7
+Summary: A production-grade middleware for AI agents to perform on-chain payments and verifiable consent.
+Author: AgentGuard Team
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: py-algorand-sdk>=2.0.0
+Dynamic: license-file
+
+# AgentGuard: Secure Payment & Consent Middleware for AI Agents
+
+[![PyPI version](https://img.shields.io/pypi/v/agentguard-python-sdk.svg)](https://pypi.org/project/agentguard-python-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/agentguard-python-sdk.svg)](https://pypi.org/project/agentguard-python-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**AgentGuard** is a production-grade cryptographic middleware that enables AI agents to perform autonomous on-chain payments and generate verifiable consent proofs. It provides a zero-trust bridge between AI agents and the Algorand blockchain.
+
+---
+
+## ⚡ The Problem: Key Vulnerability in AI Agents
+AI Agents often need to handle money (micropayments) and user data (consent). If you give an agent a private key, you risk:
+1.  **Key Theft**: The agent's memory or logs leaking the seed.
+2.  **Unintended Spending**: The agent's LLM "hallucinating" a purchase.
+3.  **Non-Compliance**: No audit trail of *why* a payment was made (violating DPDP standards).
+
+## 🛡️ The Solution: AgentGuard Architecture
+AgentGuard solves this using a **Vaulted Delegation** architecture:
+- **Hardened Vault (MCP)**: Your sensitive keys stay in a secure isolated server.
+- **Verifiable Consent**: The SDK signs a cryptographic intent (Purpose + Amount + ID) which the Vault verifies before signing a blockchain transaction.
+- **Zero-Trust**: The Backend never sees your keys; it only relays signed instructions.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install agentguard-python-sdk
+```
+
+---
+
+## 🚀 Quick Start (Request Signing)
+
+AgentGuard uses **dual-identity cryptography**. Your **Signer ID** (Master Account) authenticates the request, while your **Principal ID** (Vault/LogicSig) handles the funds.
+
+```python
+import asyncio
+from agentguard import AgentGuardClient
+
+async def main():
+    # Initialize client with your Signer Identity
+    # Note: private_key is used ONLY for request signing, never for on-chain spend.
+    async with AgentGuardClient(
+        principal_id="LOGICSIG_OR_VAULT_ADDRESS",
+        private_key="MASTER_ACCOUNT_SEED_B64",
+        backend_url="https://agentguard-backend-9s8j.onrender.com"
+    ) as client:
+        
+        # Access a premium resource
+        # The SDK automatically handles: 402 Challenge -> Consent Signing -> Payment Relay
+        receipt = await client.pay_and_fetch(
+            resource_url="https://premium-intel.service/data",
+            purpose="Market Analysis",
+            amount_algo="0.1" # Optional: SDK can auto-probe price
+        )
+        
+        print(f"✅ Success! Data: {receipt.data}")
+        print(f"🔗 Audit Trail: {receipt.audit_url}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## 🧩 Core Concepts
+
+### 1. Identity Separation (Zero-Trust)
+AgentGuard separates the **Signer** from the **Payer**:
+*   **Signer (`signer_id`)**: Your Master Account. It signs the "Intent to Pay" via the SDK.
+*   **Payer (`principal_id`)**: A LogicSig or Vault account. It contains the funds and has a pre-approved policy to pay only when the Master Account signs.
+
+### 2. Purpose-Bound Consent (DPDP)
+Every payment requires a `purpose` string. AgentGuard hashes this purpose into the blockchain transaction. This creates an irrefutable audit trail proving *exactly* what the user (or agent) consented to at the time of payment.
+
+### 3. Capability Delegation (LogicSigs)
+You can authorize specific amounts or windows of time for your agent:
+```python
+from agentguard.types import DelegatedAuthorization, AuthorizationConstraints
+
+auth = DelegatedAuthorization(
+    authorization_id="auth-uuid-123",
+    principal_id="LOGICSIG_ADDRESS",
+    logic_sig_b64="...",
+    constraints=AuthorizationConstraints(
+        max_amount_microalgos=5000000, # 5 ALGO limit
+        expires_at_unix=1716300000
+    )
+)
+await client.authorize(auth)
+```
+
+---
+
+## 🛠️ API Reference
+
+### `AgentGuardClient`
+*   `pay_and_fetch(resource_url, purpose, ...)`: The primary method. Probes a resource, extracts the price, signs consent, performs payment via the vault, and returns the data.
+*   `authorize(delegated_auth)`: Registers a LogicSig or delegated capability in the vault.
+*   `verify(tx_id)`: Checks the blockchain and audit logs to verify a previous payment's validity.
+*   `revoke(authorization_id)`: Immediately invalidates a delegated capability.
+
+---
+
+## 🔒 Security Policy
+The SDK uses `ED25519` for all request signatures. All payloads are **canonicalized** (Deterministic JSON sorting + NFC normalization) before signing to prevent "In-Flight Mutation" attacks.
+
+---
+
+© 2026 AgentGuard Team. Built for the Algorand Advanced Agentic Coding.

agentguard_python_sdk-0.2.7/README.md

@@ -0,0 +1,111 @@
+# AgentGuard: Secure Payment & Consent Middleware for AI Agents
+
+[![PyPI version](https://img.shields.io/pypi/v/agentguard-python-sdk.svg)](https://pypi.org/project/agentguard-python-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/agentguard-python-sdk.svg)](https://pypi.org/project/agentguard-python-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**AgentGuard** is a production-grade cryptographic middleware that enables AI agents to perform autonomous on-chain payments and generate verifiable consent proofs. It provides a zero-trust bridge between AI agents and the Algorand blockchain.
+
+---
+
+## ⚡ The Problem: Key Vulnerability in AI Agents
+AI Agents often need to handle money (micropayments) and user data (consent). If you give an agent a private key, you risk:
+1.  **Key Theft**: The agent's memory or logs leaking the seed.
+2.  **Unintended Spending**: The agent's LLM "hallucinating" a purchase.
+3.  **Non-Compliance**: No audit trail of *why* a payment was made (violating DPDP standards).
+
+## 🛡️ The Solution: AgentGuard Architecture
+AgentGuard solves this using a **Vaulted Delegation** architecture:
+- **Hardened Vault (MCP)**: Your sensitive keys stay in a secure isolated server.
+- **Verifiable Consent**: The SDK signs a cryptographic intent (Purpose + Amount + ID) which the Vault verifies before signing a blockchain transaction.
+- **Zero-Trust**: The Backend never sees your keys; it only relays signed instructions.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install agentguard-python-sdk
+```
+
+---
+
+## 🚀 Quick Start (Request Signing)
+
+AgentGuard uses **dual-identity cryptography**. Your **Signer ID** (Master Account) authenticates the request, while your **Principal ID** (Vault/LogicSig) handles the funds.
+
+```python
+import asyncio
+from agentguard import AgentGuardClient
+
+async def main():
+    # Initialize client with your Signer Identity
+    # Note: private_key is used ONLY for request signing, never for on-chain spend.
+    async with AgentGuardClient(
+        principal_id="LOGICSIG_OR_VAULT_ADDRESS",
+        private_key="MASTER_ACCOUNT_SEED_B64",
+        backend_url="https://agentguard-backend-9s8j.onrender.com"
+    ) as client:
+        
+        # Access a premium resource
+        # The SDK automatically handles: 402 Challenge -> Consent Signing -> Payment Relay
+        receipt = await client.pay_and_fetch(
+            resource_url="https://premium-intel.service/data",
+            purpose="Market Analysis",
+            amount_algo="0.1" # Optional: SDK can auto-probe price
+        )
+        
+        print(f"✅ Success! Data: {receipt.data}")
+        print(f"🔗 Audit Trail: {receipt.audit_url}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## 🧩 Core Concepts
+
+### 1. Identity Separation (Zero-Trust)
+AgentGuard separates the **Signer** from the **Payer**:
+*   **Signer (`signer_id`)**: Your Master Account. It signs the "Intent to Pay" via the SDK.
+*   **Payer (`principal_id`)**: A LogicSig or Vault account. It contains the funds and has a pre-approved policy to pay only when the Master Account signs.
+
+### 2. Purpose-Bound Consent (DPDP)
+Every payment requires a `purpose` string. AgentGuard hashes this purpose into the blockchain transaction. This creates an irrefutable audit trail proving *exactly* what the user (or agent) consented to at the time of payment.
+
+### 3. Capability Delegation (LogicSigs)
+You can authorize specific amounts or windows of time for your agent:
+```python
+from agentguard.types import DelegatedAuthorization, AuthorizationConstraints
+
+auth = DelegatedAuthorization(
+    authorization_id="auth-uuid-123",
+    principal_id="LOGICSIG_ADDRESS",
+    logic_sig_b64="...",
+    constraints=AuthorizationConstraints(
+        max_amount_microalgos=5000000, # 5 ALGO limit
+        expires_at_unix=1716300000
+    )
+)
+await client.authorize(auth)
+```
+
+---
+
+## 🛠️ API Reference
+
+### `AgentGuardClient`
+*   `pay_and_fetch(resource_url, purpose, ...)`: The primary method. Probes a resource, extracts the price, signs consent, performs payment via the vault, and returns the data.
+*   `authorize(delegated_auth)`: Registers a LogicSig or delegated capability in the vault.
+*   `verify(tx_id)`: Checks the blockchain and audit logs to verify a previous payment's validity.
+*   `revoke(authorization_id)`: Immediately invalidates a delegated capability.
+
+---
+
+## 🔒 Security Policy
+The SDK uses `ED25519` for all request signatures. All payloads are **canonicalized** (Deterministic JSON sorting + NFC normalization) before signing to prevent "In-Flight Mutation" attacks.
+
+---
+
+© 2026 AgentGuard Team. Built for the Algorand Advanced Agentic Coding.

{agentguard_python_sdk-0.2.5 → agentguard_python_sdk-0.2.7}/agentguard/__init__.py

@@ -27,7 +27,7 @@ from .types import (
     RevocationReceipt
 )
 
-__version__ = "0.2.2"
+__version__ = "0.2.7"
 
 __all__ = [
     "AgentGuardClient",

{agentguard_python_sdk-0.2.5 → agentguard_python_sdk-0.2.7}/agentguard/client.py

@@ -192,7 +192,8 @@ class AgentGuardClient:
             timestamp=timestamp,
             fiduciary_name=self.config.fiduciary_name,
             fiduciary_version=self.config.fiduciary_version,
-            hash_version=self.config.hash_version
+            hash_version=self.config.hash_version,
+            signer_id=self.signer_id
         )
         
         from agentguard_crypto.models import CanonicalPaymentPayload
@@ -337,6 +338,7 @@ class AgentGuardClient:
                     from agentguard_crypto.models import CanonicalPaymentPayload
                     
                     canonical_payload = CanonicalPaymentPayload(
+                        signer_id=local_proof.get("signer_id", self.signer_id),
                         principal_id=local_proof.get("principal_id", self.wallet_address),
                         resource_url=local_proof.get("resource_url", ""),
                         purpose=local_proof.get("purpose", ""),

{agentguard_python_sdk-0.2.5 → agentguard_python_sdk-0.2.7}/agentguard/consent.py

@@ -30,7 +30,8 @@ def generate_consent_proof(
     hash_version: int = 4,
     authorization_id: str = "",
     correlation_id: str = "",
-    idempotency_key: str = ""
+    idempotency_key: str = "",
+    signer_id: str = None
 ) -> tuple[str, int]:
     """
     High-level helper to generate a consent hash and return the timestamp used.
@@ -42,6 +43,7 @@ def generate_consent_proof(
     
     # Generate the canonical model
     canonical_model = CanonicalPaymentPayload(
+        signer_id=signer_id or principal_id,
         principal_id=principal_id,
         resource_url=resource_url,
         purpose=purpose,

{agentguard_python_sdk-0.2.5 → agentguard_python_sdk-0.2.7}/agentguard_crypto/models.py

@@ -1,108 +1,109 @@
-from typing import Optional
-from pydantic import BaseModel, Field, StrictInt
-from .canonical import canonicalize_payload
-
-SCHEMA_VERSION = 1
-
-class CanonicalPayloadMixin:
-    """
-    PROTOCOL LAYER: Single Serialization Authority.
-    
-    ALL serialization MUST derive from _serialize().
-    Direct model_dump() calls are FORBIDDEN in protocol code.
-    
-    Invariant enforced by construction:
-        wire_payload == signed_payload == verified_payload
-    """
-
-    def _serialize(self) -> dict:
-        """SINGLE INTERNAL SERIALIZATION SOURCE.
-        Every external serialization method MUST derive from this.
-        Uses exclude_unset=True to prevent default injection drift."""
-        return self.model_dump(exclude_unset=True)
-
-    def to_canonical_bytes(self) -> bytes:
-        """Returns deterministic canonical bytes for signing/verification."""
-        return canonicalize_payload(self._serialize())
-
-    def to_wire_dict(self) -> dict:
-        """Returns the EXACT dict for HTTP transport.
-        Guaranteed identical field set to what is signed/verified."""
-        return self._serialize()
-
-    # Backward compatibility alias (used by signing.py, consent.py, payment.py)
-    get_canonical_bytes = to_canonical_bytes
-
-class CanonicalPaymentPayload(BaseModel, CanonicalPayloadMixin):
-    """
-    SINGLE SOURCE OF TRUTH (Phase 2).
-    Represents the exact fields that are signed and verified for Payment.
-    """
-    # Core Identity
-    principal_id: str
-    resource_url: str
-    purpose: str
-    microalgos: StrictInt = Field(gt=0)
-    
-    # Target
-    receiver_address: Optional[str] = None
-    receiver: Optional[str] = None
-    
-    # Cryptographic Nonces
-    nonce: str
-    timestamp: int
-    
-    # Authorization Context
-    authorization_id: Optional[str] = None
-    consent_hash: str
-    
-    # Correlation & Idempotency
-    idempotency_key: str
-    correlation_id: str
-    session_id: Optional[str] = None
-    
-    # Fiduciary Metadata (Phase A1)
-    fiduciary_name: Optional[str] = None
-    fiduciary_version: Optional[str] = None
-    hash_version: Optional[int] = 1
-    
-    # Versioning (Phase 5)
-    schema_version: int = Field(default=SCHEMA_VERSION)
-
-
-class CanonicalAuthorizationPayload(BaseModel, CanonicalPayloadMixin):
-    """
-    STRICTLY contains ONLY authorization lifecycle fields.
-    """
-    principal_id: str
-    logic_sig_b64: str
-    max_amount: StrictInt = Field(gt=0)
-    expires_at_unix: StrictInt
-    receiver: Optional[str] = None
-    purpose_hash: Optional[str] = None
-    authorization_id: Optional[str] = None
-    timestamp: int
-    nonce: str
-    schema_version: int = Field(default=SCHEMA_VERSION)
-
-
-class CanonicalRevokePayload(BaseModel, CanonicalPayloadMixin):
-    """
-    STRICTLY contains ONLY revocation fields.
-    """
-    principal_id: str
-    authorization_id: str
-    timestamp: int
-    nonce: str
-    schema_version: int = Field(default=SCHEMA_VERSION)
-
-
-class CanonicalRegistrationPayload(BaseModel, CanonicalPayloadMixin):
-    """
-    STRICTLY contains ONLY registration fields.
-    """
-    principal_id: str
-    budget_microalgos: Optional[StrictInt] = None
-    timestamp: int
-    nonce: str
-    schema_version: int = Field(default=SCHEMA_VERSION)
+from typing import Optional
+from pydantic import BaseModel, Field, StrictInt
+from .canonical import canonicalize_payload
+
+SCHEMA_VERSION = 1
+
+class CanonicalPayloadMixin:
+    """
+    PROTOCOL LAYER: Single Serialization Authority.
+    
+    ALL serialization MUST derive from _serialize().
+    Direct model_dump() calls are FORBIDDEN in protocol code.
+    
+    Invariant enforced by construction:
+        wire_payload == signed_payload == verified_payload
+    """
+
+    def _serialize(self) -> dict:
+        """SINGLE INTERNAL SERIALIZATION SOURCE.
+        Every external serialization method MUST derive from this.
+        Uses exclude_unset=True to prevent default injection drift."""
+        return self.model_dump(exclude_unset=True)
+
+    def to_canonical_bytes(self) -> bytes:
+        """Returns deterministic canonical bytes for signing/verification."""
+        return canonicalize_payload(self._serialize())
+
+    def to_wire_dict(self) -> dict:
+        """Returns the EXACT dict for HTTP transport.
+        Guaranteed identical field set to what is signed/verified."""
+        return self._serialize()
+
+    # Backward compatibility alias (used by signing.py, consent.py, payment.py)
+    get_canonical_bytes = to_canonical_bytes
+
+class CanonicalPaymentPayload(BaseModel, CanonicalPayloadMixin):
+    """
+    SINGLE SOURCE OF TRUTH (Phase 2).
+    Represents the exact fields that are signed and verified for Payment.
+    """
+    # Core Identity
+    signer_id: str
+    principal_id: str
+    resource_url: str
+    purpose: str
+    microalgos: StrictInt = Field(gt=0)
+    
+    # Target
+    receiver_address: Optional[str] = None
+    receiver: Optional[str] = None
+    
+    # Cryptographic Nonces
+    nonce: str
+    timestamp: int
+    
+    # Authorization Context
+    authorization_id: Optional[str] = None
+    consent_hash: str
+    
+    # Correlation & Idempotency
+    idempotency_key: str
+    correlation_id: str
+    session_id: Optional[str] = None
+    
+    # Fiduciary Metadata (Phase A1)
+    fiduciary_name: Optional[str] = None
+    fiduciary_version: Optional[str] = None
+    hash_version: Optional[int] = 1
+    
+    # Versioning (Phase 5)
+    schema_version: int = Field(default=SCHEMA_VERSION)
+
+
+class CanonicalAuthorizationPayload(BaseModel, CanonicalPayloadMixin):
+    """
+    STRICTLY contains ONLY authorization lifecycle fields.
+    """
+    principal_id: str
+    logic_sig_b64: str
+    max_amount: StrictInt = Field(gt=0)
+    expires_at_unix: StrictInt
+    receiver: Optional[str] = None
+    purpose_hash: Optional[str] = None
+    authorization_id: Optional[str] = None
+    timestamp: int
+    nonce: str
+    schema_version: int = Field(default=SCHEMA_VERSION)
+
+
+class CanonicalRevokePayload(BaseModel, CanonicalPayloadMixin):
+    """
+    STRICTLY contains ONLY revocation fields.
+    """
+    principal_id: str
+    authorization_id: str
+    timestamp: int
+    nonce: str
+    schema_version: int = Field(default=SCHEMA_VERSION)
+
+
+class CanonicalRegistrationPayload(BaseModel, CanonicalPayloadMixin):
+    """
+    STRICTLY contains ONLY registration fields.
+    """
+    principal_id: str
+    budget_microalgos: Optional[StrictInt] = None
+    timestamp: int
+    nonce: str
+    schema_version: int = Field(default=SCHEMA_VERSION)

{agentguard_python_sdk-0.2.5 → agentguard_python_sdk-0.2.7}/agentguard_crypto/signing.py

@@ -1,76 +1,87 @@
-import base64
-import nacl.signing
-import nacl.encoding
-from typing import Any
-from .models import CanonicalPaymentPayload
-
-def sign_payload(payload: Any, private_key_b64: str) -> str:
-    """
-    Signs a CanonicalPaymentPayload (Phase 4).
-    Expects private_key_b64 (32-byte seed in b64).
-    """
-    seed = base64.b64decode(private_key_b64)
-    if len(seed) > 32:
-        seed = seed[:32]
-        
-    signing_key = nacl.signing.SigningKey(seed)
-    canonical_bytes = payload.get_canonical_bytes()
-    
-    signature = signing_key.sign(canonical_bytes)
-    return base64.b64encode(signature.signature).decode("utf-8")
-
-def verify_signature(payload: Any, signature_b64: str, wallet_address: str) -> bool:
-    """
-    Verifies a CanonicalPaymentPayload signature (Phase 4).
-    wallet_address is used as the public key.
-    """
-    from algosdk import encoding
-    import nacl.exceptions
-    
-    # 1. Get canonical bytes
-    canonical_bytes = payload.get_canonical_bytes()
-    
-    # 2. Decode signature and key
-    sig_bytes = base64.b64decode(signature_b64)
-    pub_key_bytes = encoding.decode_address(wallet_address)
-    verify_key = nacl.signing.VerifyKey(pub_key_bytes)
-    
-    # 3. Verify
-    try:
-        verify_key.verify(canonical_bytes, sig_bytes)
-        return True
-    except nacl.exceptions.BadSignatureError:
-        return False
-
-
-def verify_raw_signature(raw_payload_dict: dict, signature_b64: str, wallet_address: str) -> bool:
-    """
-    PRODUCTION-GRADE: Verifies signature against raw transport payload.
-    
-    NO model reconstruction. Canonicalizes the raw wire dict directly.
-    This eliminates Pydantic hydration drift, default injection, and
-    triple-reconstruction attacks.
-    
-    Flow: raw_wire_dict → canonicalize → verify
-    
-    This is how Stripe, AWS SigV4, and WebAuthn verify signatures:
-    against exact transport bytes, never reconstructed model state.
-    """
-    from .canonical import canonicalize_payload
-    from algosdk import encoding
-    import nacl.exceptions
-    
-    # 1. Canonicalize raw transport payload directly
-    canonical_bytes = canonicalize_payload(raw_payload_dict)
-    
-    # 2. Decode signature and public key
-    sig_bytes = base64.b64decode(signature_b64)
-    pub_key_bytes = encoding.decode_address(wallet_address)
-    verify_key = nacl.signing.VerifyKey(pub_key_bytes)
-    
-    # 3. Verify
-    try:
-        verify_key.verify(canonical_bytes, sig_bytes)
-        return True
-    except nacl.exceptions.BadSignatureError:
-        return False
+import base64
+import nacl.signing
+import nacl.encoding
+from typing import Any
+from .models import CanonicalPaymentPayload
+
+def sign_payload(payload: Any, private_key_b64: str) -> str:
+    """
+    Signs a CanonicalPaymentPayload (Phase 4).
+    Expects private_key_b64 (32-byte seed in b64).
+    """
+    seed = base64.b64decode(private_key_b64)
+    if len(seed) > 32:
+        seed = seed[:32]
+        
+    signing_key = nacl.signing.SigningKey(seed)
+    canonical_bytes = payload.get_canonical_bytes()
+    
+    signature = signing_key.sign(canonical_bytes)
+    return base64.b64encode(signature.signature).decode("utf-8")
+
+def verify_signature(payload: Any, signature_b64: str, wallet_address: str) -> bool:
+    """
+    Verifies a CanonicalPaymentPayload signature (Phase 4).
+    wallet_address is used as the public key.
+    """
+    from algosdk import encoding
+    import nacl.exceptions
+    
+    # 1. Get canonical bytes
+    canonical_bytes = payload.get_canonical_bytes()
+    
+    # 2. Decode signature and key
+    sig_bytes = base64.b64decode(signature_b64)
+    pub_key_bytes = encoding.decode_address(wallet_address)
+    verify_key = nacl.signing.VerifyKey(pub_key_bytes)
+    
+    # 3. Verify
+    try:
+        verify_key.verify(canonical_bytes, sig_bytes)
+        return True
+    except nacl.exceptions.BadSignatureError:
+        return False
+
+
+def verify_raw_signature(raw_payload_dict: dict, signature_b64: str, wallet_address: str) -> bool:
+    """
+    PRODUCTION-GRADE: Verifies signature against raw transport payload.
+    
+    NO model reconstruction. Canonicalizes the raw wire dict directly.
+    This eliminates Pydantic hydration drift, default injection, and
+    triple-reconstruction attacks.
+    
+    Flow: raw_wire_dict → canonicalize → verify
+    
+    This is how Stripe, AWS SigV4, and WebAuthn verify signatures:
+    against exact transport bytes, never reconstructed model state.
+    """
+    from .canonical import canonicalize_payload
+    from algosdk import encoding
+    import nacl.exceptions
+    
+    # 1. Canonicalize raw transport payload directly
+    canonical_bytes = canonicalize_payload(raw_payload_dict)
+    
+    # 2. Decode signature and public key
+    sig_bytes = base64.b64decode(signature_b64)
+    pub_key_bytes = encoding.decode_address(wallet_address)
+    verify_key = nacl.signing.VerifyKey(pub_key_bytes)
+    
+    # 3. Verify
+    try:
+        verify_key.verify(canonical_bytes, sig_bytes)
+        return True
+    except nacl.exceptions.BadSignatureError:
+        return False
+
+def get_signer_address(private_key_b64: str) -> str:
+    """
+    Derives the Algorand address (signer_id) from a b64 private key seed.
+    """
+    from algosdk import encoding
+    seed = base64.b64decode(private_key_b64)
+    if len(seed) > 32:
+        seed = seed[:32]
+    signing_key = nacl.signing.SigningKey(seed)
+    return encoding.encode_address(signing_key.verify_key.encode())

agentguard_python_sdk-0.2.7/agentguard_python_sdk.egg-info/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: agentguard-python-sdk
+Version: 0.2.7
+Summary: A production-grade middleware for AI agents to perform on-chain payments and verifiable consent.
+Author: AgentGuard Team
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: py-algorand-sdk>=2.0.0
+Dynamic: license-file
+
+# AgentGuard: Secure Payment & Consent Middleware for AI Agents
+
+[![PyPI version](https://img.shields.io/pypi/v/agentguard-python-sdk.svg)](https://pypi.org/project/agentguard-python-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/agentguard-python-sdk.svg)](https://pypi.org/project/agentguard-python-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**AgentGuard** is a production-grade cryptographic middleware that enables AI agents to perform autonomous on-chain payments and generate verifiable consent proofs. It provides a zero-trust bridge between AI agents and the Algorand blockchain.
+
+---
+
+## ⚡ The Problem: Key Vulnerability in AI Agents
+AI Agents often need to handle money (micropayments) and user data (consent). If you give an agent a private key, you risk:
+1.  **Key Theft**: The agent's memory or logs leaking the seed.
+2.  **Unintended Spending**: The agent's LLM "hallucinating" a purchase.
+3.  **Non-Compliance**: No audit trail of *why* a payment was made (violating DPDP standards).
+
+## 🛡️ The Solution: AgentGuard Architecture
+AgentGuard solves this using a **Vaulted Delegation** architecture:
+- **Hardened Vault (MCP)**: Your sensitive keys stay in a secure isolated server.
+- **Verifiable Consent**: The SDK signs a cryptographic intent (Purpose + Amount + ID) which the Vault verifies before signing a blockchain transaction.
+- **Zero-Trust**: The Backend never sees your keys; it only relays signed instructions.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install agentguard-python-sdk
+```
+
+---
+
+## 🚀 Quick Start (Request Signing)
+
+AgentGuard uses **dual-identity cryptography**. Your **Signer ID** (Master Account) authenticates the request, while your **Principal ID** (Vault/LogicSig) handles the funds.
+
+```python
+import asyncio
+from agentguard import AgentGuardClient
+
+async def main():
+    # Initialize client with your Signer Identity
+    # Note: private_key is used ONLY for request signing, never for on-chain spend.
+    async with AgentGuardClient(
+        principal_id="LOGICSIG_OR_VAULT_ADDRESS",
+        private_key="MASTER_ACCOUNT_SEED_B64",
+        backend_url="https://agentguard-backend-9s8j.onrender.com"
+    ) as client:
+        
+        # Access a premium resource
+        # The SDK automatically handles: 402 Challenge -> Consent Signing -> Payment Relay
+        receipt = await client.pay_and_fetch(
+            resource_url="https://premium-intel.service/data",
+            purpose="Market Analysis",
+            amount_algo="0.1" # Optional: SDK can auto-probe price
+        )
+        
+        print(f"✅ Success! Data: {receipt.data}")
+        print(f"🔗 Audit Trail: {receipt.audit_url}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## 🧩 Core Concepts
+
+### 1. Identity Separation (Zero-Trust)
+AgentGuard separates the **Signer** from the **Payer**:
+*   **Signer (`signer_id`)**: Your Master Account. It signs the "Intent to Pay" via the SDK.
+*   **Payer (`principal_id`)**: A LogicSig or Vault account. It contains the funds and has a pre-approved policy to pay only when the Master Account signs.
+
+### 2. Purpose-Bound Consent (DPDP)
+Every payment requires a `purpose` string. AgentGuard hashes this purpose into the blockchain transaction. This creates an irrefutable audit trail proving *exactly* what the user (or agent) consented to at the time of payment.
+
+### 3. Capability Delegation (LogicSigs)
+You can authorize specific amounts or windows of time for your agent:
+```python
+from agentguard.types import DelegatedAuthorization, AuthorizationConstraints
+
+auth = DelegatedAuthorization(
+    authorization_id="auth-uuid-123",
+    principal_id="LOGICSIG_ADDRESS",
+    logic_sig_b64="...",
+    constraints=AuthorizationConstraints(
+        max_amount_microalgos=5000000, # 5 ALGO limit
+        expires_at_unix=1716300000
+    )
+)
+await client.authorize(auth)
+```
+
+---
+
+## 🛠️ API Reference
+
+### `AgentGuardClient`
+*   `pay_and_fetch(resource_url, purpose, ...)`: The primary method. Probes a resource, extracts the price, signs consent, performs payment via the vault, and returns the data.
+*   `authorize(delegated_auth)`: Registers a LogicSig or delegated capability in the vault.
+*   `verify(tx_id)`: Checks the blockchain and audit logs to verify a previous payment's validity.
+*   `revoke(authorization_id)`: Immediately invalidates a delegated capability.
+
+---
+
+## 🔒 Security Policy
+The SDK uses `ED25519` for all request signatures. All payloads are **canonicalized** (Deterministic JSON sorting + NFC normalization) before signing to prevent "In-Flight Mutation" attacks.
+
+---
+
+© 2026 AgentGuard Team. Built for the Algorand Advanced Agentic Coding.

{agentguard_python_sdk-0.2.5 → agentguard_python_sdk-0.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentguard-python-sdk"
-version = "0.2.5"
+version = "0.2.7"
 description = "A production-grade middleware for AI agents to perform on-chain payments and verifiable consent."
 readme = "README.md"
 requires-python = ">=3.9"

agentguard_python_sdk-0.2.5/PKG-INFO

@@ -1,94 +0,0 @@
-Metadata-Version: 2.4
-Name: agentguard-python-sdk
-Version: 0.2.5
-Summary: A production-grade middleware for AI agents to perform on-chain payments and verifiable consent.
-Author: AgentGuard Team
-License-Expression: MIT
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: pydantic-settings>=2.0.0
-Requires-Dist: pynacl>=1.5.0
-Requires-Dist: py-algorand-sdk>=2.0.0
-Dynamic: license-file
-
-# AgentGuard SDK
-
-AgentGuard is a production-grade middleware that enables AI agents to perform on-chain payments and generate verifiable consent proofs in compliance with DPDP (Digital Personal Data Protection) standards.
-
-By isolating private keys in a hardened **MCP Server (Vault)** and using the **AgentGuard Backend (Dispatcher)** as a secure proxy, the SDK allows developers to add monetization and compliance to their agents with zero blockchain complexity.
-
-## Installation
-
-```bash
-pip install agentguard-python-sdk
-```
-
-## Quick Start (3-Line Usage)
-
-```python
-import asyncio
-from agentguard import AgentGuardClient
-from agentguard.types import DelegatedAuthorization, AuthorizationConstraints, NonceContext, AuthorizationMetadata
-
-async def main():
-    # 1. Initialize the client
-    # NOTE: The backend requires a cryptographic signature on `/pay`.
-    # Provide `private_key` as a base64-encoded Algorand private key seed for request signing.
-    async with AgentGuardClient(
-        wallet_address="YOUR_WALLET_ADDRESS",
-        private_key="YOUR_PRIVATE_KEY_B64",
-        backend_url="https://agentguard-backend-9s8j.onrender.com"
-    ) as client:
-        
-        # 1.5 Authorize a capability (LogicSig)
-        auth = DelegatedAuthorization(
-            authorization_id="YOUR_AUTHORIZATION_ID",
-            principal_id="YOUR_WALLET_ADDRESS",
-            logic_sig_b64="YOUR_SIGNED_LOGICSIG_BASE64",
-            constraints=AuthorizationConstraints(
-                max_amount_microalgos=1000000,
-                expires_at_unix=1900000000,
-                max_txns_per_window=10,
-                window_seconds=3600
-            ),
-            nonce_context=NonceContext(lease_strategy="deterministic", scope="session"),
-            metadata=AuthorizationMetadata(created_at=1716000000, sdk_version="0.2.2", delegation_type="LogicSig")
-        )
-        await client.authorize(auth)
-        
-        # 2. Perform a secure payment (includes automatic DPDP consent hashing)
-        receipt = await client.pay_and_fetch(
-            resource_url="https://api.stock.com/reliance",
-            amount_algo="0.05",
-            purpose="Financial Analysis",
-            authorization_id="YOUR_AUTHORIZATION_ID"
-        )
-        print(f"Payment Successful! TX ID: {receipt.tx_id}")
-
-        # 3. Verify compliance audit trail
-        proof = await client.verify(receipt.tx_id)
-        print(f"On-Chain Verified: {proof.verified}")
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```
-
-## Architecture
-
-1.  **SDK**: Generates UUID nonces and SHA256 consent hashes.
-2.  **Backend**: Proxies requests to the internal vault and maintains audit records.
-3.  **MCP Server (Vault)**: A hardened, isolated environment that signs transactions using Algorand.
-4.  **Algorand Blockchain**: Provides the irrefutable proof-of-consent and payment settlement.
-
-## Features
-
-- **Async First**: Built on `httpx` for high-performance agentic loops.
-- **Zero-Trust**: Private keys never leave the vault.
-- **DPDP Compliant**: Automatic cryptographic logging of purpose-bound consent.
-- **Simple Audit**: Direct links to blockchain explorers for every transaction.
-
----
-© 2026 AgentGuard Team. Built for the Algorand Ecosystem.

agentguard_python_sdk-0.2.5/README.md

@@ -1,78 +0,0 @@
-# AgentGuard SDK
-
-AgentGuard is a production-grade middleware that enables AI agents to perform on-chain payments and generate verifiable consent proofs in compliance with DPDP (Digital Personal Data Protection) standards.
-
-By isolating private keys in a hardened **MCP Server (Vault)** and using the **AgentGuard Backend (Dispatcher)** as a secure proxy, the SDK allows developers to add monetization and compliance to their agents with zero blockchain complexity.
-
-## Installation
-
-```bash
-pip install agentguard-python-sdk
-```
-
-## Quick Start (3-Line Usage)
-
-```python
-import asyncio
-from agentguard import AgentGuardClient
-from agentguard.types import DelegatedAuthorization, AuthorizationConstraints, NonceContext, AuthorizationMetadata
-
-async def main():
-    # 1. Initialize the client
-    # NOTE: The backend requires a cryptographic signature on `/pay`.
-    # Provide `private_key` as a base64-encoded Algorand private key seed for request signing.
-    async with AgentGuardClient(
-        wallet_address="YOUR_WALLET_ADDRESS",
-        private_key="YOUR_PRIVATE_KEY_B64",
-        backend_url="https://agentguard-backend-9s8j.onrender.com"
-    ) as client:
-        
-        # 1.5 Authorize a capability (LogicSig)
-        auth = DelegatedAuthorization(
-            authorization_id="YOUR_AUTHORIZATION_ID",
-            principal_id="YOUR_WALLET_ADDRESS",
-            logic_sig_b64="YOUR_SIGNED_LOGICSIG_BASE64",
-            constraints=AuthorizationConstraints(
-                max_amount_microalgos=1000000,
-                expires_at_unix=1900000000,
-                max_txns_per_window=10,
-                window_seconds=3600
-            ),
-            nonce_context=NonceContext(lease_strategy="deterministic", scope="session"),
-            metadata=AuthorizationMetadata(created_at=1716000000, sdk_version="0.2.2", delegation_type="LogicSig")
-        )
-        await client.authorize(auth)
-        
-        # 2. Perform a secure payment (includes automatic DPDP consent hashing)
-        receipt = await client.pay_and_fetch(
-            resource_url="https://api.stock.com/reliance",
-            amount_algo="0.05",
-            purpose="Financial Analysis",
-            authorization_id="YOUR_AUTHORIZATION_ID"
-        )
-        print(f"Payment Successful! TX ID: {receipt.tx_id}")
-
-        # 3. Verify compliance audit trail
-        proof = await client.verify(receipt.tx_id)
-        print(f"On-Chain Verified: {proof.verified}")
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```
-
-## Architecture
-
-1.  **SDK**: Generates UUID nonces and SHA256 consent hashes.
-2.  **Backend**: Proxies requests to the internal vault and maintains audit records.
-3.  **MCP Server (Vault)**: A hardened, isolated environment that signs transactions using Algorand.
-4.  **Algorand Blockchain**: Provides the irrefutable proof-of-consent and payment settlement.
-
-## Features
-
-- **Async First**: Built on `httpx` for high-performance agentic loops.
-- **Zero-Trust**: Private keys never leave the vault.
-- **DPDP Compliant**: Automatic cryptographic logging of purpose-bound consent.
-- **Simple Audit**: Direct links to blockchain explorers for every transaction.
-
----
-© 2026 AgentGuard Team. Built for the Algorand Ecosystem.

agentguard_python_sdk-0.2.5/agentguard_python_sdk.egg-info/PKG-INFO

@@ -1,94 +0,0 @@
-Metadata-Version: 2.4
-Name: agentguard-python-sdk
-Version: 0.2.5
-Summary: A production-grade middleware for AI agents to perform on-chain payments and verifiable consent.
-Author: AgentGuard Team
-License-Expression: MIT
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: pydantic-settings>=2.0.0
-Requires-Dist: pynacl>=1.5.0
-Requires-Dist: py-algorand-sdk>=2.0.0
-Dynamic: license-file
-
-# AgentGuard SDK
-
-AgentGuard is a production-grade middleware that enables AI agents to perform on-chain payments and generate verifiable consent proofs in compliance with DPDP (Digital Personal Data Protection) standards.
-
-By isolating private keys in a hardened **MCP Server (Vault)** and using the **AgentGuard Backend (Dispatcher)** as a secure proxy, the SDK allows developers to add monetization and compliance to their agents with zero blockchain complexity.
-
-## Installation
-
-```bash
-pip install agentguard-python-sdk
-```
-
-## Quick Start (3-Line Usage)
-
-```python
-import asyncio
-from agentguard import AgentGuardClient
-from agentguard.types import DelegatedAuthorization, AuthorizationConstraints, NonceContext, AuthorizationMetadata
-
-async def main():
-    # 1. Initialize the client
-    # NOTE: The backend requires a cryptographic signature on `/pay`.
-    # Provide `private_key` as a base64-encoded Algorand private key seed for request signing.
-    async with AgentGuardClient(
-        wallet_address="YOUR_WALLET_ADDRESS",
-        private_key="YOUR_PRIVATE_KEY_B64",
-        backend_url="https://agentguard-backend-9s8j.onrender.com"
-    ) as client:
-        
-        # 1.5 Authorize a capability (LogicSig)
-        auth = DelegatedAuthorization(
-            authorization_id="YOUR_AUTHORIZATION_ID",
-            principal_id="YOUR_WALLET_ADDRESS",
-            logic_sig_b64="YOUR_SIGNED_LOGICSIG_BASE64",
-            constraints=AuthorizationConstraints(
-                max_amount_microalgos=1000000,
-                expires_at_unix=1900000000,
-                max_txns_per_window=10,
-                window_seconds=3600
-            ),
-            nonce_context=NonceContext(lease_strategy="deterministic", scope="session"),
-            metadata=AuthorizationMetadata(created_at=1716000000, sdk_version="0.2.2", delegation_type="LogicSig")
-        )
-        await client.authorize(auth)
-        
-        # 2. Perform a secure payment (includes automatic DPDP consent hashing)
-        receipt = await client.pay_and_fetch(
-            resource_url="https://api.stock.com/reliance",
-            amount_algo="0.05",
-            purpose="Financial Analysis",
-            authorization_id="YOUR_AUTHORIZATION_ID"
-        )
-        print(f"Payment Successful! TX ID: {receipt.tx_id}")
-
-        # 3. Verify compliance audit trail
-        proof = await client.verify(receipt.tx_id)
-        print(f"On-Chain Verified: {proof.verified}")
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```
-
-## Architecture
-
-1.  **SDK**: Generates UUID nonces and SHA256 consent hashes.
-2.  **Backend**: Proxies requests to the internal vault and maintains audit records.
-3.  **MCP Server (Vault)**: A hardened, isolated environment that signs transactions using Algorand.
-4.  **Algorand Blockchain**: Provides the irrefutable proof-of-consent and payment settlement.
-
-## Features
-
-- **Async First**: Built on `httpx` for high-performance agentic loops.
-- **Zero-Trust**: Private keys never leave the vault.
-- **DPDP Compliant**: Automatic cryptographic logging of purpose-bound consent.
-- **Simple Audit**: Direct links to blockchain explorers for every transaction.
-
----
-© 2026 AgentGuard Team. Built for the Algorand Ecosystem.