@7h3/protocol 0.5.0 → 0.5.1

package/sdk/python/protocol_7h3/replay.py

@@ -1,98 +0,0 @@
-"""
-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

@@ -1,116 +0,0 @@
-"""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

@@ -1,40 +0,0 @@
-[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

@@ -1,110 +0,0 @@
-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

@@ -1,206 +0,0 @@
-"""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()