Merge pull request #5 from Helixar-AI/feat/hdp-crewai-package

feat: add hdp-crewai Python middleware package

Author: asiridalugoda

packages/hdp-crewai/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hdp-crewai"
+version = "0.1.0"
+description = "HDP (Human Delegation Provenance) middleware for CrewAI — cryptographic audit trail for multi-agent task delegation"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "crewai>=0.80.0",
+    "cryptography>=42.0.0",
+    "jcs>=0.2.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Helixar-AI/HDP"
+Repository = "https://github.com/Helixar-AI/HDP"
+Issues = "https://github.com/crewAIInc/crewAI/issues/5102"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hdp_crewai"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

packages/hdp-crewai/src/hdp_crewai/__init__.py

@@ -0,0 +1,19 @@
+"""hdp-crewai — HDP delegation provenance middleware for CrewAI."""
+
+from ._types import HdpPrincipal, HdpScope, HdpToken, HopRecord, DataClassification
+from .middleware import HdpMiddleware, ScopePolicy, HDPScopeViolationError
+from .verify import verify_chain, VerificationResult, HopVerification
+
+__all__ = [
+    "HdpMiddleware",
+    "ScopePolicy",
+    "HDPScopeViolationError",
+    "HdpPrincipal",
+    "HdpScope",
+    "HdpToken",
+    "HopRecord",
+    "DataClassification",
+    "verify_chain",
+    "VerificationResult",
+    "HopVerification",
+]

packages/hdp-crewai/src/hdp_crewai/_crypto.py

@@ -0,0 +1,78 @@
+"""Cryptographic primitives for HDP — Ed25519 signing/verification with RFC 8785 canonical JSON.
+
+Matches the signing scheme in the TypeScript SDK (src/crypto/sign.ts + src/crypto/verify.ts):
+  - Root: canonicalize({header, principal, scope}) → Ed25519 → base64url
+  - Hop:  canonicalize({chain: [...], root_sig: <value>}) → Ed25519 → base64url
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+import jcs
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+
+
+def _b64url(sig_bytes: bytes) -> str:
+    """Encode bytes as unpadded base64url (matches Buffer.toString('base64url') in Node)."""
+    return base64.urlsafe_b64encode(sig_bytes).rstrip(b"=").decode()
+
+
+def _canonicalize(obj: Any) -> bytes:
+    """RFC 8785 canonical JSON bytes."""
+    return jcs.canonicalize(obj)
+
+
+def sign_root(unsigned_token: dict, private_key_bytes: bytes, kid: str) -> dict:
+    """Sign the root token over {header, principal, scope} and return a signature dict."""
+    subset = {f: unsigned_token[f] for f in ["header", "principal", "scope"] if f in unsigned_token}
+    message = _canonicalize(subset)
+    key = Ed25519PrivateKey.from_private_bytes(private_key_bytes)
+    sig_bytes = key.sign(message)
+    return {
+        "alg": "Ed25519",
+        "kid": kid,
+        "value": _b64url(sig_bytes),
+        "signed_fields": ["header", "principal", "scope"],
+    }
+
+
+def sign_hop(cumulative_chain: list[dict], root_sig_value: str, private_key_bytes: bytes) -> str:
+    """Sign a hop over the cumulative chain + root signature value."""
+    payload = {"chain": cumulative_chain, "root_sig": root_sig_value}
+    message = _canonicalize(payload)
+    key = Ed25519PrivateKey.from_private_bytes(private_key_bytes)
+    sig_bytes = key.sign(message)
+    return _b64url(sig_bytes)
+
+
+def _b64url_decode(s: str) -> bytes:
+    """Decode unpadded base64url string to bytes."""
+    padding = 4 - len(s) % 4
+    return base64.urlsafe_b64decode(s + "=" * padding)
+
+
+def verify_root(token: dict, public_key: Ed25519PublicKey) -> bool:
+    """Verify the root signature over {header, principal, scope}."""
+    try:
+        subset = {f: token[f] for f in ["header", "principal", "scope"] if f in token}
+        message = _canonicalize(subset)
+        sig_bytes = _b64url_decode(token["signature"]["value"])
+        public_key.verify(sig_bytes, message)
+        return True
+    except (InvalidSignature, KeyError, Exception):
+        return False
+
+
+def verify_hop(cumulative_chain: list[dict], root_sig_value: str, hop_signature: str, public_key: Ed25519PublicKey) -> bool:
+    """Verify a single hop signature over the cumulative chain + root sig value."""
+    try:
+        payload = {"chain": cumulative_chain, "root_sig": root_sig_value}
+        message = _canonicalize(payload)
+        sig_bytes = _b64url_decode(hop_signature)
+        public_key.verify(sig_bytes, message)
+        return True
+    except (InvalidSignature, Exception):
+        return False

packages/hdp-crewai/src/hdp_crewai/_types.py

@@ -0,0 +1,69 @@
+"""Python types mirroring the HDP TypeScript SDK schema."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Optional
+
+DataClassification = Literal["public", "internal", "confidential", "restricted"]
+AgentType = Literal["orchestrator", "sub-agent", "tool-executor", "custom"]
+PrincipalIdType = Literal["email", "uuid", "did", "poh", "opaque"]
+
+
+@dataclass
+class HdpHeader:
+    token_id: str
+    issued_at: int
+    expires_at: int
+    session_id: str
+    version: str = "0.1"
+    parent_token_id: Optional[str] = None
+
+
+@dataclass
+class HdpPrincipal:
+    id: str
+    id_type: PrincipalIdType
+    display_name: Optional[str] = None
+    metadata: Optional[dict[str, Any]] = None
+
+
+@dataclass
+class HdpScope:
+    intent: str
+    data_classification: DataClassification
+    network_egress: bool
+    persistence: bool
+    authorized_tools: Optional[list[str]] = None
+    authorized_resources: Optional[list[str]] = None
+    max_hops: Optional[int] = None
+
+
+@dataclass
+class HdpSignature:
+    alg: str
+    kid: str
+    value: str
+    signed_fields: list[str] = field(default_factory=lambda: ["header", "principal", "scope"])
+
+
+@dataclass
+class HopRecord:
+    seq: int
+    agent_id: str
+    agent_type: AgentType
+    timestamp: int
+    action_summary: str
+    parent_hop: int
+    hop_signature: str
+    agent_fingerprint: Optional[str] = None
+
+
+@dataclass
+class HdpToken:
+    hdp: str
+    header: HdpHeader
+    principal: HdpPrincipal
+    scope: HdpScope
+    chain: list[HopRecord]
+    signature: HdpSignature