7h3-protocol 0.4.0__tar.gz

7h3_protocol-0.4.0/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+sdk/rust/target/
+**/__pycache__/
+*.tsbuildinfo
+.DS_Store

7h3_protocol-0.4.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: 7h3-protocol
+Version: 0.4.0
+Summary: 7h3 Protocol — Python SDK. Deterministic, signed, replay-safe AI-to-AI messaging. Wire version 7h3/0.1.
+Project-URL: Homepage, https://github.com/IceMasterT/7h3-protocol
+Project-URL: Repository, https://github.com/IceMasterT/7h3-protocol
+Project-URL: Documentation, https://github.com/IceMasterT/7h3-protocol/tree/main/sdk/python
+Project-URL: Changelog, https://github.com/IceMasterT/7h3-protocol/blob/main/CHANGELOG.md
+License: MIT
+Keywords: 7h3,agent,ed25519,mcp,protocol,replay-protection,signing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: crypto
+Requires-Dist: cryptography>=41.0; extra == 'crypto'
+Provides-Extra: nacl
+Requires-Dist: pynacl>=1.5; extra == 'nacl'
+Description-Content-Type: text/markdown
+
+# 7h3 Protocol AIP Python SDK (Skeleton)
+
+Minimal reference SDK for `aip/0.1` parity with the TypeScript implementation.
+
+## Included
+
+- deterministic canonicalization
+- HS256 HMAC signing and verification
+- ED25519 signing and verification (requires `cryptography` package)
+- compact wire encode/decode
+- envelope validation helpers (version, required fields, TTL)
+- conformance tests using shared vectors from `conformance/aip_v0_1.json`
+
+## Run conformance tests
+
+```bash
+PYTHONPATH=sdk/python python3 -m unittest discover -s sdk/python/tests -v
+```

7h3_protocol-0.4.0/README.md

@@ -0,0 +1,18 @@
+# 7h3 Protocol AIP Python SDK (Skeleton)
+
+Minimal reference SDK for `aip/0.1` parity with the TypeScript implementation.
+
+## Included
+
+- deterministic canonicalization
+- HS256 HMAC signing and verification
+- ED25519 signing and verification (requires `cryptography` package)
+- compact wire encode/decode
+- envelope validation helpers (version, required fields, TTL)
+- conformance tests using shared vectors from `conformance/aip_v0_1.json`
+
+## Run conformance tests
+
+```bash
+PYTHONPATH=sdk/python python3 -m unittest discover -s sdk/python/tests -v
+```

7h3_protocol-0.4.0/protocol_7h3/__init__.py

@@ -0,0 +1,46 @@
+from .protocol import (  # noqa: F401
+    canonicalize_envelope,
+    decode_envelope,
+    encode_envelope_compact,
+    sign_canonical_payload_ed25519,
+    sign_canonical_payload_hmac,
+    sign_envelope_ed25519,
+    sign_envelope_hmac,
+    validate_envelope,
+    verify_canonical_payload_ed25519,
+    verify_canonical_payload_hmac,
+    verify_envelope_ed25519,
+    verify_envelope_hmac,
+)
+
+try:
+    from .http import (  # noqa: F401
+        DEFAULT_HEADER, KeyRegistry, StaticKeyRegistry,
+        verify_http_envelope, sign_http_request, build_signed_request_headers,
+    )
+except ImportError:
+    pass
+
+try:
+    from .webhook import (  # noqa: F401
+        WEBHOOK_SIG_HEADER, WEBHOOK_TS_HEADER,
+        sign_webhook, sign_webhook_hmac, verify_webhook, verify_webhook_hmac, consume_webhook,
+    )
+except ImportError:
+    pass
+
+try:
+    from .queue import (  # noqa: F401
+        sign_queue_message, verify_queue_message, verify_queue_batch,
+    )
+except ImportError:
+    pass
+
+try:
+    from .keys import (  # noqa: F401
+        KeyEntry, WellKnownKeysDocument, ManagedKeyPair,
+        KeyRotationManager, RevocationRegistry,
+        fetch_well_known_keys,
+    )
+except ImportError:
+    pass

7h3_protocol-0.4.0/protocol_7h3/http.py

@@ -0,0 +1,212 @@
+"""HTTP binding for 7h3 Protocol — signs/verifies per-request envelopes."""
+from __future__ import annotations
+
+import json
+import time
+import uuid
+import os
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from .protocol import (
+    verify_envelope_ed25519,
+    verify_envelope_hmac,
+    sign_envelope_ed25519,
+    validate_envelope,
+    ProtocolDiagnostic,
+)
+
+DEFAULT_HEADER = "x-7h3-envelope"
+
+VerifyFailReason = str  # 'missing-header' | 'malformed-envelope' | 'unknown-sender' | 'invalid-signature' | 'ttl-expired'
+
+
+class KeyRegistry:
+    """Abstract key registry — subclass to implement custom lookup."""
+
+    def get_public_key(self, sender_id: str) -> Optional[str]:
+        raise NotImplementedError
+
+    def get_shared_secret(self, key_id: str) -> Optional[str]:
+        return None
+
+
+class StaticKeyRegistry(KeyRegistry):
+    """In-memory registry backed by a dict {sender_id: public_key_b64url}."""
+
+    def __init__(self, keys: Dict[str, str]):
+        self._keys = keys
+
+    def get_public_key(self, sender_id: str) -> Optional[str]:
+        return self._keys.get(sender_id)
+
+
+def _make_envelope(
+    sender: str,
+    ttl_ms: int,
+    body: Dict[str, Any],
+    recipient: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Build an unsigned envelope dict."""
+    header: Dict[str, Any] = {
+        "version": "7h3/0.1",
+        "messageId": str(uuid.uuid4()),
+        "timestampMs": int(time.time() * 1000),
+        "ttlMs": ttl_ms,
+        "sender": sender,
+        "nonce": os.urandom(8).hex(),
+    }
+    if recipient is not None:
+        header["recipient"] = recipient
+    return {"header": header, "body": body}
+
+
+def verify_http_envelope(
+    headers: Dict[str, str],
+    registry: KeyRegistry,
+    *,
+    header_name: str = DEFAULT_HEADER,
+    strict_ttl: bool = True,
+) -> Tuple[bool, Optional[dict], Optional[VerifyFailReason]]:
+    """
+    Verify a 7h3 envelope from HTTP headers.
+    Returns (ok, envelope_dict, reason).
+    reason is None on success, a VerifyFailReason string on failure.
+    """
+    # Headers may arrive with mixed case — normalise
+    normalised = {k.lower(): v for k, v in headers.items()}
+    raw = normalised.get(header_name.lower())
+    if not raw:
+        return False, None, "missing-header"
+
+    try:
+        envelope = json.loads(raw)
+    except Exception:
+        return False, None, "malformed-envelope"
+
+    if not isinstance(envelope, dict) or "header" not in envelope or "signature" not in envelope:
+        return False, None, "malformed-envelope"
+
+    if strict_ttl:
+        now_ms = int(time.time() * 1000)
+        diags: list[ProtocolDiagnostic] = validate_envelope(envelope, now_ms=now_ms)
+        errors = [d for d in diags if d.level == "error"]
+        if errors:
+            return False, None, "ttl-expired"
+
+    sender = envelope.get("header", {}).get("sender", "")
+    alg = envelope.get("signature", {}).get("alg", "")
+
+    if alg == "ED25519":
+        pub_key = registry.get_public_key(sender)
+        if not pub_key:
+            return False, None, "unknown-sender"
+        valid = verify_envelope_ed25519(envelope, pub_key)
+        if not valid:
+            return False, None, "invalid-signature"
+    elif alg == "HS256":
+        key_id = envelope.get("signature", {}).get("keyId", "")
+        secret = registry.get_shared_secret(key_id)
+        if not secret:
+            return False, None, "unknown-sender"
+        valid = verify_envelope_hmac(envelope, secret)
+        if not valid:
+            return False, None, "invalid-signature"
+    else:
+        return False, None, "malformed-envelope"
+
+    return True, envelope, None
+
+
+def sign_http_request(
+    envelope_without_sig: dict,
+    private_key: str,
+    *,
+    header_name: str = DEFAULT_HEADER,
+) -> Dict[str, str]:
+    """Sign an envelope and return HTTP headers dict to add to your request."""
+    signed = sign_envelope_ed25519(envelope_without_sig, private_key)
+    return {header_name: json.dumps(signed, separators=(",", ":"))}
+
+
+def build_signed_request_headers(
+    sender: str,
+    private_key: str,
+    *,
+    recipient: Optional[str] = None,
+    ttl_ms: int = 60_000,
+    content: str = "",
+    header_name: str = DEFAULT_HEADER,
+) -> Dict[str, str]:
+    """Convenience: build envelope + sign in one call. Returns headers dict."""
+    envelope = _make_envelope(
+        sender=sender,
+        ttl_ms=ttl_ms,
+        body={"intent": "TASK", "content": content},
+        recipient=recipient,
+    )
+    return sign_http_request(envelope, private_key, header_name=header_name)
+
+
+# --- Framework integrations ---
+
+
+def starlette_middleware_factory(registry: KeyRegistry, *, header_name: str = DEFAULT_HEADER):
+    """
+    Returns an ASGI middleware class for Starlette/FastAPI.
+
+    Usage:
+        app.add_middleware(starlette_middleware_factory(registry))
+    """
+    try:
+        from starlette.middleware.base import BaseHTTPMiddleware
+        from starlette.requests import Request
+        from starlette.responses import JSONResponse
+    except ImportError as e:
+        raise ImportError("starlette is required: pip install starlette") from e
+
+    class Protocol7h3Middleware(BaseHTTPMiddleware):
+        async def dispatch(self, request: Request, call_next: Callable) -> Any:
+            headers = dict(request.headers)
+            ok, envelope, reason = verify_http_envelope(
+                headers, registry, header_name=header_name
+            )
+            if not ok:
+                return JSONResponse(
+                    {"error": "7h3: request verification failed", "reason": reason},
+                    status_code=401,
+                )
+            request.state.envelope_7h3 = envelope
+            return await call_next(request)
+
+    return Protocol7h3Middleware
+
+
+def flask_before_request_factory(registry: KeyRegistry, *, header_name: str = DEFAULT_HEADER):
+    """
+    Returns a Flask before_request handler.
+
+    Usage:
+        app.before_request(flask_before_request_factory(registry))
+    """
+
+    def before_request():
+        try:
+            from flask import request as flask_req, g
+        except ImportError as e:
+            raise ImportError("flask is required: pip install flask") from e
+
+        headers = dict(flask_req.headers)
+        ok, envelope, reason = verify_http_envelope(headers, registry, header_name=header_name)
+        if not ok:
+            from flask import make_response
+
+            resp = make_response(
+                json.dumps({"error": "7h3: request verification failed", "reason": reason}),
+                401,
+            )
+            resp.headers["Content-Type"] = "application/json"
+            return resp
+        g.envelope_7h3 = envelope
+        return None  # continue
+
+    return before_request

7h3_protocol-0.4.0/protocol_7h3/keys.py

@@ -0,0 +1,149 @@
+"""Key infrastructure for 7h3 Protocol — discovery, rotation, revocation."""
+from __future__ import annotations
+import json
+import time
+import threading
+from typing import Dict, List, Optional, Any
+from dataclasses import dataclass, field
+
+WELL_KNOWN_PATH = "/.well-known/7h3-keys"
+REVOCATION_PATH = "/.well-known/7h3-revoked"
+
+@dataclass
+class KeyEntry:
+    id: str
+    algorithm: str  # 'Ed25519'
+    public_key: str  # SPKI base64url
+    created: int     # Unix ms
+    expires: Optional[int] = None
+    revoked: bool = False
+    revoked_at: Optional[int] = None
+
+@dataclass
+class WellKnownKeysDocument:
+    version: str  # '7h3/0.1'
+    updated: int
+    keys: List[KeyEntry]
+
+    def to_json(self) -> str:
+        keys_list = []
+        for k in self.keys:
+            entry = {
+                "id": k.id, "algorithm": k.algorithm, "publicKey": k.public_key,
+                "created": k.created,
+            }
+            if k.expires is not None: entry["expires"] = k.expires
+            if k.revoked: entry["revoked"] = True
+            if k.revoked_at is not None: entry["revokedAt"] = k.revoked_at
+            keys_list.append(entry)
+        return json.dumps({"version": self.version, "updated": self.updated, "keys": keys_list}, separators=(",", ":"))
+
+    @classmethod
+    def from_json(cls, data: str) -> "WellKnownKeysDocument":
+        d = json.loads(data)
+        keys = []
+        for k in d.get("keys", []):
+            keys.append(KeyEntry(
+                id=k["id"], algorithm=k["algorithm"], public_key=k["publicKey"],
+                created=k["created"], expires=k.get("expires"), revoked=k.get("revoked", False),
+                revoked_at=k.get("revokedAt"),
+            ))
+        return cls(version=d["version"], updated=d["updated"], keys=keys)
+
+
+def fetch_well_known_keys(base_url: str, *, timeout: float = 5.0) -> WellKnownKeysDocument:
+    """Fetch the /.well-known/7h3-keys document from a base URL."""
+    import urllib.request
+    url = base_url.rstrip("/") + WELL_KNOWN_PATH
+    with urllib.request.urlopen(url, timeout=timeout) as resp:
+        data = resp.read().decode("utf-8")
+    return WellKnownKeysDocument.from_json(data)
+
+
+@dataclass
+class ManagedKeyPair:
+    id: str
+    public_key: str   # SPKI base64url
+    private_key: str  # PKCS8 base64url
+    created: int
+    expires_at: Optional[int] = None
+
+
+class KeyRotationManager:
+    """Manages Ed25519 key pairs with automatic rotation."""
+
+    def __init__(self, max_age_ms: int = 86_400_000, overlap_ms: int = 3_600_000):
+        self.max_age_ms = max_age_ms
+        self.overlap_ms = overlap_ms
+        self._keys: List[ManagedKeyPair] = []
+        self._lock = threading.Lock()
+
+    def add_key(self, pair: ManagedKeyPair) -> None:
+        with self._lock:
+            self._keys.append(pair)
+
+    def get_current_key(self) -> Optional[ManagedKeyPair]:
+        """Return the most recently created non-expired key."""
+        now = int(time.time() * 1000)
+        with self._lock:
+            active = [k for k in self._keys if not k.expires_at or k.expires_at > now]
+            if not active:
+                return None
+            return sorted(active, key=lambda k: k.created, reverse=True)[0]
+
+    def rotate_if_needed(self) -> Optional[ManagedKeyPair]:
+        """Generate a new key if the current one is too old.
+
+        NOTE: generate_ed25519_keypair does not exist in protocol.py.
+        Callers should supply keys externally via add_key() rather than
+        relying on this method.
+        """
+        raise NotImplementedError(
+            "rotate_if_needed requires generate_ed25519_keypair which is not "
+            "implemented in protocol.py. Supply new keys externally via add_key()."
+        )
+
+    def get_well_known_document(self) -> WellKnownKeysDocument:
+        now = int(time.time() * 1000)
+        with self._lock:
+            entries = []
+            for k in self._keys:
+                entry = KeyEntry(
+                    id=k.id, algorithm="Ed25519", public_key=k.public_key,
+                    created=k.created, expires=k.expires_at,
+                    revoked=bool(k.expires_at and k.expires_at < now),
+                )
+                entries.append(entry)
+        return WellKnownKeysDocument(version="7h3/0.1", updated=now, keys=entries)
+
+
+class RevocationRegistry:
+    """Tracks revoked key IDs."""
+
+    def __init__(self):
+        self._revoked: Dict[str, Dict[str, Any]] = {}
+        self._lock = threading.Lock()
+
+    def revoke(self, key_id: str, reason: Optional[str] = None) -> None:
+        with self._lock:
+            self._revoked[key_id] = {"revokedAt": int(time.time() * 1000), "reason": reason}
+
+    def is_revoked(self, key_id: str) -> bool:
+        with self._lock:
+            return key_id in self._revoked
+
+    def get_list(self) -> dict:
+        now = int(time.time() * 1000)
+        with self._lock:
+            revoked = [
+                {"id": kid, "revokedAt": v["revokedAt"], **({"reason": v["reason"]} if v["reason"] else {})}
+                for kid, v in self._revoked.items()
+            ]
+        return {"version": "7h3/0.1", "updated": now, "revokedKeys": revoked}
+
+    def import_list(self, revocation_list: dict) -> None:
+        with self._lock:
+            for entry in revocation_list.get("revokedKeys", []):
+                kid = entry["id"]
+                if kid not in self._revoked:
+                    self._revoked[kid] = {"revokedAt": entry["revokedAt"], "reason": entry.get("reason")}