@7h3/protocol 0.1.2 → 0.5.0

package/sdk/python/protocol_7h3/replay.py

@@ -0,0 +1,98 @@
+"""
+Redis-backed replay store for the 7h3 Protocol Python SDK.
+
+Provides atomic nonce deduplication using Redis SET NX PX semantics.
+The ``redis`` package is optional — an ImportError is raised at construction
+time (not at module import) when it is absent, so the rest of the SDK remains
+usable without installing Redis dependencies.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Any
+
+
+class RedisReplayStore:
+    """
+    Atomic replay detection backed by Redis.
+
+    Uses ``SET key value NX PX ttl_ms`` so the first caller atomically claims
+    the nonce and all subsequent callers are identified as replays — safe
+    across multiple horizontally-scaled gateway instances.
+
+    Parameters
+    ----------
+    redis_url:
+        Redis connection URL passed to ``redis.from_url()``.  Ignored when
+        *client* is provided.
+    key_prefix:
+        Namespace prefix prepended to every nonce key. Default ``'7h3:nonce:'``.
+    client:
+        Pre-constructed Redis client (any object that exposes ``set`` and
+        ``close``).  When supplied, *redis_url* is ignored.
+
+    Raises
+    ------
+    ImportError
+        At construction time when *redis_url* is provided but the ``redis``
+        package is not installed.
+    """
+
+    def __init__(
+        self,
+        redis_url: Optional[str] = None,
+        key_prefix: str = "7h3:nonce:",
+        client: Optional[Any] = None,
+    ) -> None:
+        self.key_prefix = key_prefix
+
+        if client is not None:
+            self._client = client
+        else:
+            try:
+                import redis  # type: ignore[import]
+            except ImportError as exc:
+                raise ImportError(
+                    "The 'redis' package is required to use RedisReplayStore. "
+                    "Install it with: pip install redis"
+                ) from exc
+
+            url = redis_url or "redis://localhost:6379"
+            self._client = redis.from_url(url, decode_responses=True)
+
+    def check(self, key: str, ttl_ms: int) -> bool:
+        """
+        Atomically check and register a nonce.
+
+        Returns
+        -------
+        bool
+            ``False`` if the nonce is fresh (first time seen — the key was set
+            in Redis), or ``True`` if the nonce is a replay (the key already
+            existed in Redis and SET NX was blocked).
+        """
+        redis_key = f"{self.key_prefix}{key}"
+        px = max(1, ttl_ms)
+        result = self._client.set(redis_key, "1", nx=True, px=px)
+        # redis-py returns True when the key was set, None when NX blocked it
+        return result is None
+
+    def close(self) -> None:
+        """Close the underlying Redis connection."""
+        close = getattr(self._client, "close", None)
+        if close is not None:
+            close()
+
+
+def create_redis_replay_store(redis_url: str, key_prefix: str = "7h3:nonce:") -> RedisReplayStore:
+    """
+    Convenience factory — create a :class:`RedisReplayStore` from a Redis URL.
+
+    Parameters
+    ----------
+    redis_url:
+        Redis connection URL, e.g. ``'redis://localhost:6379'``.
+    key_prefix:
+        Key namespace prefix. Default ``'7h3:nonce:'``.
+    """
+    return RedisReplayStore(redis_url=redis_url, key_prefix=key_prefix)

package/sdk/python/protocol_7h3/webhook.py

@@ -0,0 +1,116 @@
+"""Webhook binding for 7h3 Protocol — lightweight per-payload signing."""
+from __future__ import annotations
+import json
+import time
+from typing import Any, Dict, Optional, TypeVar, Union
+
+WEBHOOK_SIG_HEADER = "x-7h3-sig"
+WEBHOOK_TS_HEADER = "x-7h3-ts"
+WEBHOOK_DEFAULT_TTL_MS = 300_000  # 5 minutes
+
+
+def _webhook_signing_payload(timestamp_ms: int, body: str) -> str:
+    return f"{timestamp_ms}.{body}"
+
+
+def sign_webhook(
+    payload: Union[str, bytes],
+    private_key: str,
+    *,
+    ttl_ms: int = WEBHOOK_DEFAULT_TTL_MS,
+) -> Dict[str, str]:
+    """Sign a webhook payload. Returns headers dict with x-7h3-sig and x-7h3-ts."""
+    from .protocol import sign_canonical_payload_ed25519
+
+    body = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+    ts = int(time.time() * 1000)
+    signing_payload = _webhook_signing_payload(ts, body)
+    sig = sign_canonical_payload_ed25519(signing_payload, private_key)
+    return {WEBHOOK_SIG_HEADER: sig, WEBHOOK_TS_HEADER: str(ts)}
+
+
+def sign_webhook_hmac(
+    payload: Union[str, bytes],
+    secret: str,
+    *,
+    ttl_ms: int = WEBHOOK_DEFAULT_TTL_MS,
+) -> Dict[str, str]:
+    """Sign a webhook payload with HMAC-SHA256 shared secret."""
+    from .protocol import sign_canonical_payload_hmac
+
+    body = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+    ts = int(time.time() * 1000)
+    signing_payload = _webhook_signing_payload(ts, body)
+    sig = sign_canonical_payload_hmac(signing_payload, secret)
+    return {WEBHOOK_SIG_HEADER: sig, WEBHOOK_TS_HEADER: str(ts)}
+
+
+def verify_webhook(
+    payload: Union[str, bytes],
+    headers: Dict[str, str],
+    public_key: str,
+    *,
+    max_age_ms: int = WEBHOOK_DEFAULT_TTL_MS,
+) -> bool:
+    """Verify an Ed25519 webhook signature. Returns True/False."""
+    from .protocol import verify_canonical_payload_ed25519
+
+    body = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+    # normalise header keys
+    normalised = {k.lower(): v for k, v in headers.items()}
+    sig = normalised.get(WEBHOOK_SIG_HEADER.lower())
+    ts_str = normalised.get(WEBHOOK_TS_HEADER.lower())
+    if not sig or not ts_str:
+        return False
+    try:
+        ts = int(ts_str)
+    except ValueError:
+        return False
+    now_ms = int(time.time() * 1000)
+    if now_ms - ts > max_age_ms:
+        return False
+    signing_payload = _webhook_signing_payload(ts, body)
+    return verify_canonical_payload_ed25519(signing_payload, sig, public_key)
+
+
+def verify_webhook_hmac(
+    payload: Union[str, bytes],
+    headers: Dict[str, str],
+    secret: str,
+    *,
+    max_age_ms: int = WEBHOOK_DEFAULT_TTL_MS,
+) -> bool:
+    """Verify an HMAC webhook signature."""
+    from .protocol import verify_canonical_payload_hmac
+
+    body = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+    normalised = {k.lower(): v for k, v in headers.items()}
+    sig = normalised.get(WEBHOOK_SIG_HEADER.lower())
+    ts_str = normalised.get(WEBHOOK_TS_HEADER.lower())
+    if not sig or not ts_str:
+        return False
+    try:
+        ts = int(ts_str)
+    except ValueError:
+        return False
+    now_ms = int(time.time() * 1000)
+    if now_ms - ts > max_age_ms:
+        return False
+    signing_payload = _webhook_signing_payload(ts, body)
+    return verify_canonical_payload_hmac(signing_payload, sig, secret)
+
+
+T = TypeVar("T")
+
+
+def consume_webhook(
+    payload: str,
+    headers: Dict[str, str],
+    public_key: str,
+    *,
+    max_age_ms: int = WEBHOOK_DEFAULT_TTL_MS,
+) -> Any:
+    """Parse and verify a JSON webhook payload. Raises ValueError on failure."""
+    if not verify_webhook(payload, headers, public_key, max_age_ms=max_age_ms):
+        raise ValueError("7h3: webhook signature verification failed")
+    return json.loads(payload)

package/sdk/python/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "7h3-protocol"
+version = "0.5.0"
+description = "7h3 Protocol — Python SDK. Deterministic, signed, replay-safe AI-to-AI messaging. Wire version 7h3/0.1."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["7h3", "agent", "protocol", "ed25519", "mcp", "signing", "replay-protection"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security :: Cryptography",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Internet",
+]
+dependencies = []
+
+[project.optional-dependencies]
+crypto = ["cryptography>=41.0"]
+nacl = ["PyNaCl>=1.5"]
+
+[project.urls]
+Homepage = "https://github.com/IceMasterT/7h3-protocol"
+Repository = "https://github.com/IceMasterT/7h3-protocol"
+Documentation = "https://github.com/IceMasterT/7h3-protocol/tree/main/sdk/python"
+Changelog = "https://github.com/IceMasterT/7h3-protocol/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["protocol_7h3"]

package/sdk/python/tests/test_conformance.py

@@ -0,0 +1,110 @@
+import json
+import pathlib
+import unittest
+
+from protocol_7h3.protocol import (
+    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,
+)
+
+
+ROOT = pathlib.Path(__file__).resolve().parents[3]
+VECTORS_PATH = ROOT / "conformance" / "7h3_v0_1.json"
+
+
+class ConformanceTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        with VECTORS_PATH.open("r", encoding="utf-8") as handle:
+            cls.payload = json.load(handle)
+
+    def test_vectors_match_canonical_and_signatures(self) -> None:
+        for vector in self.payload["vectors"]:
+            envelope = vector["envelope"]
+            canonical = canonicalize_envelope(envelope)
+            self.assertEqual(canonical, vector["canonical"])
+
+            signature = sign_canonical_payload_hmac(canonical, vector["secret"])
+            self.assertEqual(signature, vector["signature"])
+            self.assertTrue(
+                verify_canonical_payload_hmac(canonical, signature, vector["secret"])
+            )
+            self.assertFalse(
+                verify_canonical_payload_hmac(
+                    canonical, signature, vector["secret"] + "-bad"
+                )
+            )
+
+            signed = sign_envelope_hmac(envelope, vector["secret"], vector["keyId"])
+            self.assertTrue(verify_envelope_hmac(signed, vector["secret"]))
+            self.assertFalse(verify_envelope_hmac(signed, vector["secret"] + "-bad"))
+
+    def test_compact_roundtrip(self) -> None:
+        for vector in self.payload["vectors"]:
+            signed = sign_envelope_hmac(
+                vector["envelope"], vector["secret"], vector["keyId"]
+            )
+            raw = encode_envelope_compact(signed)
+            decoded = decode_envelope(raw)
+            self.assertEqual(decoded, signed)
+
+    def test_ttl_validation(self) -> None:
+        vector = self.payload["vectors"][0]
+        envelope = vector["envelope"]
+
+        valid = validate_envelope(
+            envelope, now_ms=envelope["header"]["timestampMs"] + 1
+        )
+        self.assertFalse(any(d.message == "Message TTL expired" for d in valid))
+
+        expired = validate_envelope(
+            envelope,
+            now_ms=envelope["header"]["timestampMs"] + envelope["header"]["ttlMs"] + 1,
+        )
+        self.assertTrue(any(d.message == "Message TTL expired" for d in expired))
+
+    def test_ed25519_vectors_if_crypto_available(self) -> None:
+        vectors = self.payload.get("ed25519Vectors", [])
+        if not vectors:
+            self.skipTest("No ED25519 vectors present")
+
+        for vector in vectors:
+            envelope = vector["envelope"]
+            canonical = canonicalize_envelope(envelope)
+            self.assertEqual(canonical, vector["canonical"])
+
+            try:
+                signature = sign_canonical_payload_ed25519(
+                    canonical, vector["privateKey"]
+                )
+            except RuntimeError as exc:
+                if "cryptography package is required" in str(exc):
+                    self.skipTest("cryptography package unavailable for ED25519")
+                raise
+
+            self.assertEqual(signature, vector["signature"])
+            self.assertTrue(
+                verify_canonical_payload_ed25519(
+                    canonical, signature, vector["publicKey"]
+                )
+            )
+
+            signed = sign_envelope_ed25519(
+                envelope, vector["privateKey"], vector["keyId"]
+            )
+            self.assertTrue(verify_envelope_ed25519(signed, vector["publicKey"]))
+            self.assertEqual(signed["signature"]["alg"], "ED25519")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/sdk/python/tests/test_encryption.py

@@ -0,0 +1,206 @@
+"""Tests for protocol_7h3.encryption — X25519 + ChaCha20-Poly1305 E2E encryption."""
+from __future__ import annotations
+
+import base64
+import json
+import time
+import unittest
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from cryptography.hazmat.primitives import serialization
+
+from protocol_7h3.encryption import (
+    generate_x25519_keypair,
+    seal_envelope,
+    open_envelope,
+    _encrypt_body,
+    _decrypt_body,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _b64url_encode(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
+
+
+def _generate_ed25519_keypair():
+    """Generate Ed25519 keypair in PKCS8/SPKI DER format (base64url) — matches TS protocol.ts."""
+    priv = Ed25519PrivateKey.generate()
+    pub = priv.public_key()
+    priv_der = priv.private_bytes(
+        serialization.Encoding.DER,
+        serialization.PrivateFormat.PKCS8,
+        serialization.NoEncryption(),
+    )
+    pub_der = pub.public_bytes(
+        serialization.Encoding.DER,
+        serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    return _b64url_encode(priv_der), _b64url_encode(pub_der)
+
+
+def _make_envelope(body: dict) -> dict:
+    now_ms = int(time.time() * 1000)
+    return {
+        "header": {
+            "version": "7h3/0.1",
+            "messageId": f"msg-{now_ms}-test",
+            "timestampMs": now_ms,
+            "ttlMs": 60_000,
+            "sender": "agent-alice",
+            "recipient": "agent-bob",
+            "nonce": _b64url_encode(__import__("os").urandom(12)),
+        },
+        "body": body,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+class TestGenerateX25519Keypair(unittest.TestCase):
+    """Test 1: generate_x25519_keypair returns 32-byte base64url keys."""
+
+    def test_key_format(self):
+        pub, priv = generate_x25519_keypair()
+        # base64url of 32 bytes = 43 chars (no padding)
+        self.assertRegex(pub, r"^[A-Za-z0-9_-]{43}$")
+        self.assertRegex(priv, r"^[A-Za-z0-9_-]{43}$")
+        # Decoded must be exactly 32 bytes
+        padding = "=" * ((4 - (len(pub) % 4)) % 4)
+        self.assertEqual(len(base64.urlsafe_b64decode(pub + padding)), 32)
+        padding = "=" * ((4 - (len(priv) % 4)) % 4)
+        self.assertEqual(len(base64.urlsafe_b64decode(priv + padding)), 32)
+
+
+class TestSealAndOpenEnvelope(unittest.TestCase):
+    """Test 2: sealEnvelope + openEnvelope round-trip recovers original body exactly."""
+
+    def test_round_trip(self):
+        recipient_pub, recipient_priv = generate_x25519_keypair()
+        sender_priv_ed, sender_pub_ed = _generate_ed25519_keypair()
+
+        original_body = {
+            "intent": "TASK",
+            "content": "Hello encrypted world!",
+            "capability": "some-cap",
+            "correlationId": "corr-123",
+        }
+        envelope = _make_envelope(original_body)
+
+        sealed = seal_envelope(envelope, recipient_pub, sender_priv_ed)
+        result = open_envelope(sealed, recipient_priv, sender_pub_ed)
+        body = result["body"]
+
+        self.assertEqual(body["intent"], original_body["intent"])
+        self.assertEqual(body["content"], original_body["content"])
+        self.assertEqual(body.get("capability"), original_body["capability"])
+        self.assertEqual(body.get("correlationId"), original_body["correlationId"])
+
+
+class TestWrongRecipientKey(unittest.TestCase):
+    """Test 3: fails with wrong recipient private key (AEAD tag mismatch)."""
+
+    def test_wrong_key_fails(self):
+        recipient_pub, _ = generate_x25519_keypair()
+        _, wrong_priv = generate_x25519_keypair()
+        sender_priv_ed, sender_pub_ed = _generate_ed25519_keypair()
+
+        envelope = _make_envelope({"intent": "PING", "content": "secret"})
+        sealed = seal_envelope(envelope, recipient_pub, sender_priv_ed)
+
+        # Use _decrypt_body directly to bypass signature check (wrong key scenario)
+        with self.assertRaises(Exception):
+            _decrypt_body(sealed["body"]["content"], wrong_priv)
+
+
+class TestTamperedSignature(unittest.TestCase):
+    """Test 4: fails if envelope signature is tampered."""
+
+    def test_tampered_signature(self):
+        recipient_pub, recipient_priv = generate_x25519_keypair()
+        sender_priv_ed, sender_pub_ed = _generate_ed25519_keypair()
+
+        envelope = _make_envelope({"intent": "PING", "content": "secret"})
+        sealed = seal_envelope(envelope, recipient_pub, sender_priv_ed)
+
+        # Tamper with signature
+        tampered = dict(sealed)
+        tampered["signature"] = dict(sealed["signature"])
+        tampered["signature"]["value"] = "A" * 86  # wrong Ed25519 sig
+
+        with self.assertRaises(ValueError) as ctx:
+            open_envelope(tampered, recipient_priv, sender_pub_ed)
+        self.assertIn("signature", str(ctx.exception).lower())
+
+
+class TestTamperedCiphertext(unittest.TestCase):
+    """Test 5: fails if ciphertext tampered (AEAD auth tag fails)."""
+
+    def test_tampered_ciphertext(self):
+        recipient_pub, recipient_priv = generate_x25519_keypair()
+
+        body = {"intent": "PING", "content": "secret"}
+        encrypted_payload_dict = _encrypt_body(body, recipient_pub)
+
+        # Flip bits in ciphertext
+        import base64
+        ct_bytes = bytearray(base64.urlsafe_b64decode(
+            encrypted_payload_dict["ciphertext"] + "=" * ((4 - len(encrypted_payload_dict["ciphertext"]) % 4) % 4)
+        ))
+        ct_bytes[0] ^= 0xFF
+        encrypted_payload_dict["ciphertext"] = base64.urlsafe_b64encode(bytes(ct_bytes)).decode().rstrip("=")
+
+        # Re-encode payload
+        tampered_content = _b64url_encode(
+            json.dumps(encrypted_payload_dict, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+        )
+
+        with self.assertRaises(Exception):
+            _decrypt_body(tampered_content, recipient_priv)
+
+
+class TestEphemeralRandomness(unittest.TestCase):
+    """Test 6: Two seal calls on same body produce different ciphertexts."""
+
+    def test_different_ciphertexts(self):
+        recipient_pub, _ = generate_x25519_keypair()
+        sender_priv_ed, _ = _generate_ed25519_keypair()
+
+        envelope1 = _make_envelope({"intent": "PING", "content": "same content"})
+        envelope2 = _make_envelope({"intent": "PING", "content": "same content"})
+
+        sealed1 = seal_envelope(envelope1, recipient_pub, sender_priv_ed)
+        sealed2 = seal_envelope(envelope2, recipient_pub, sender_priv_ed)
+
+        self.assertNotEqual(sealed1["body"]["content"], sealed2["body"]["content"])
+
+
+class TestEncryptedContentOpaque(unittest.TestCase):
+    """Test 7: Encrypted content is opaque (does not contain original body.content)."""
+
+    def test_content_is_opaque(self):
+        recipient_pub, _ = generate_x25519_keypair()
+        sender_priv_ed, _ = _generate_ed25519_keypair()
+
+        original_content = "super-secret-data-12345"
+        envelope = _make_envelope({"intent": "TASK", "content": original_content})
+
+        sealed = seal_envelope(envelope, recipient_pub, sender_priv_ed)
+
+        # The encrypted content (as JSON) should not reveal the original string
+        encrypted_content_decoded = base64.urlsafe_b64decode(
+            sealed["body"]["content"] + "=" * ((4 - len(sealed["body"]["content"]) % 4) % 4)
+        ).decode("utf-8")
+        self.assertNotIn(original_content, encrypted_content_decoded)
+        self.assertNotIn(original_content, sealed["body"]["content"])
+
+
+if __name__ == "__main__":
+    unittest.main()