@7h3/protocol 0.1.2 → 0.4.0

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.4.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_http.py

@@ -0,0 +1,305 @@
+"""Tests for protocol_7h3.http — HTTP binding."""
+from __future__ import annotations
+
+import json
+import time
+import unittest
+
+from protocol_7h3.protocol import sign_envelope_ed25519, sign_envelope_hmac
+from protocol_7h3.http import (
+    DEFAULT_HEADER,
+    KeyRegistry,
+    StaticKeyRegistry,
+    build_signed_request_headers,
+    sign_http_request,
+    verify_http_envelope,
+)
+
+# ED25519 test key pair from conformance vectors (SPKI public / PKCS8 private, base64url)
+_TEST_PUBLIC_KEY = "MCowBQYDK2VwAyEA-mUFiTQtcKN4nnD19V_-Wyy4q19OivnAutRUPhOcC78"
+_TEST_PRIVATE_KEY = "MC4CAQAwBQYDK2VwBCIEICheZbQGuDVb6hezIlcs0QnCHGxz6IhiLkC9M0qr8OOZ"
+_SENDER = "agent.ed"
+
+
+def _make_valid_envelope(ttl_ms: int = 60_000) -> dict:
+    """Return an unsigned envelope with a current timestamp."""
+    now = int(time.time() * 1000)
+    return {
+        "header": {
+            "version": "7h3/0.1",
+            "messageId": "test-msg-1",
+            "timestampMs": now,
+            "ttlMs": ttl_ms,
+            "sender": _SENDER,
+            "nonce": "test-nonce-1",
+        },
+        "body": {
+            "intent": "TASK",
+            "content": "hello http",
+        },
+    }
+
+
+def _signed_envelope(ttl_ms: int = 60_000) -> dict:
+    env = _make_valid_envelope(ttl_ms=ttl_ms)
+    return sign_envelope_ed25519(env, _TEST_PRIVATE_KEY)
+
+
+def _registry() -> StaticKeyRegistry:
+    return StaticKeyRegistry({_SENDER: _TEST_PUBLIC_KEY})
+
+
+class TestVerifyHttpEnvelopeMissingHeader(unittest.TestCase):
+    """1. verify_http_envelope: missing header."""
+
+    def test_missing_header_returns_false_and_reason(self):
+        ok, env, reason = verify_http_envelope({}, _registry())
+        self.assertFalse(ok)
+        self.assertIsNone(env)
+        self.assertEqual(reason, "missing-header")
+
+    def test_wrong_header_name_treated_as_missing(self):
+        headers = {"x-other-header": "{}"}
+        ok, env, reason = verify_http_envelope(headers, _registry())
+        self.assertFalse(ok)
+        self.assertEqual(reason, "missing-header")
+
+
+class TestVerifyHttpEnvelopeInvalidJson(unittest.TestCase):
+    """2. verify_http_envelope: invalid JSON."""
+
+    def test_malformed_json(self):
+        headers = {DEFAULT_HEADER: "not-json{{{"}
+        ok, env, reason = verify_http_envelope(headers, _registry())
+        self.assertFalse(ok)
+        self.assertIsNone(env)
+        self.assertEqual(reason, "malformed-envelope")
+
+    def test_json_without_required_keys(self):
+        headers = {DEFAULT_HEADER: json.dumps({"foo": "bar"})}
+        ok, env, reason = verify_http_envelope(headers, _registry())
+        self.assertFalse(ok)
+        self.assertEqual(reason, "malformed-envelope")
+
+    def test_json_missing_signature_key(self):
+        headers = {DEFAULT_HEADER: json.dumps({"header": {}, "body": {}})}
+        ok, env, reason = verify_http_envelope(headers, _registry())
+        self.assertFalse(ok)
+        self.assertEqual(reason, "malformed-envelope")
+
+
+class TestVerifyHttpEnvelopeValidEd25519(unittest.TestCase):
+    """3. verify_http_envelope: valid Ed25519 signed envelope."""
+
+    def test_valid_signed_envelope(self):
+        signed = _signed_envelope()
+        headers = {DEFAULT_HEADER: json.dumps(signed)}
+        ok, env, reason = verify_http_envelope(headers, _registry())
+        self.assertTrue(ok)
+        self.assertIsNotNone(env)
+        self.assertIsNone(reason)
+
+    def test_valid_envelope_mixed_case_header(self):
+        """Headers are case-insensitive per HTTP spec."""
+        signed = _signed_envelope()
+        headers = {"X-7H3-Envelope": json.dumps(signed)}
+        ok, env, reason = verify_http_envelope(headers, _registry())
+        self.assertTrue(ok)
+        self.assertIsNone(reason)
+
+    def test_returns_envelope_dict_on_success(self):
+        signed = _signed_envelope()
+        headers = {DEFAULT_HEADER: json.dumps(signed)}
+        ok, env, reason = verify_http_envelope(headers, _registry())
+        self.assertTrue(ok)
+        self.assertIn("header", env)
+        self.assertIn("body", env)
+        self.assertIn("signature", env)
+
+
+class TestVerifyHttpEnvelopeTampered(unittest.TestCase):
+    """4. verify_http_envelope: tampered envelope."""
+
+    def test_tampered_content_fails_verification(self):
+        signed = _signed_envelope()
+        # Tamper with the body content after signing
+        signed["body"]["content"] = "tampered!"
+        headers = {DEFAULT_HEADER: json.dumps(signed)}
+        ok, env, reason = verify_http_envelope(headers, _registry())
+        self.assertFalse(ok)
+        self.assertEqual(reason, "invalid-signature")
+
+    def test_tampered_sender_fails_verification(self):
+        signed = _signed_envelope()
+        signed["header"]["sender"] = "evil.agent"
+        headers = {DEFAULT_HEADER: json.dumps(signed)}
+        # evil.agent not in registry → unknown-sender
+        ok, env, reason = verify_http_envelope(headers, _registry())
+        self.assertFalse(ok)
+        self.assertIn(reason, ("unknown-sender", "invalid-signature"))
+
+    def test_tampered_signature_value_fails(self):
+        signed = _signed_envelope()
+        signed["signature"]["value"] = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
+        headers = {DEFAULT_HEADER: json.dumps(signed)}
+        ok, env, reason = verify_http_envelope(headers, _registry())
+        self.assertFalse(ok)
+        self.assertEqual(reason, "invalid-signature")
+
+
+class TestVerifyHttpEnvelopeUnknownSender(unittest.TestCase):
+    """5. verify_http_envelope: unknown sender."""
+
+    def test_unknown_sender_ed25519(self):
+        signed = _signed_envelope()
+        # Empty registry — no known senders
+        empty_registry = StaticKeyRegistry({})
+        headers = {DEFAULT_HEADER: json.dumps(signed)}
+        ok, env, reason = verify_http_envelope(headers, empty_registry)
+        self.assertFalse(ok)
+        self.assertIsNone(env)
+        self.assertEqual(reason, "unknown-sender")
+
+    def test_unknown_sender_hmac(self):
+        env = _make_valid_envelope()
+        signed = sign_envelope_hmac(env, "mysecret", "key-1")
+        headers = {DEFAULT_HEADER: json.dumps(signed)}
+
+        class NoSecretRegistry(KeyRegistry):
+            def get_public_key(self, sender_id: str):
+                return None
+            def get_shared_secret(self, key_id: str):
+                return None  # key_id "key-1" unknown
+
+        ok, result, reason = verify_http_envelope(headers, NoSecretRegistry())
+        self.assertFalse(ok)
+        self.assertEqual(reason, "unknown-sender")
+
+
+class TestSignHttpRequestRoundTrip(unittest.TestCase):
+    """6. sign_http_request + verify_http_envelope round trip."""
+
+    def test_round_trip_succeeds(self):
+        unsigned = _make_valid_envelope()
+        headers = sign_http_request(unsigned, _TEST_PRIVATE_KEY)
+        ok, env, reason = verify_http_envelope(headers, _registry())
+        self.assertTrue(ok)
+        self.assertIsNone(reason)
+        self.assertEqual(env["body"]["content"], "hello http")
+
+    def test_round_trip_strict_ttl_expired(self):
+        # Create envelope that is already expired
+        past_ms = int(time.time() * 1000) - 120_000  # 2 minutes ago
+        envelope = {
+            "header": {
+                "version": "7h3/0.1",
+                "messageId": "expired-msg",
+                "timestampMs": past_ms,
+                "ttlMs": 1_000,  # 1 second TTL → already expired
+                "sender": _SENDER,
+                "nonce": "nonce-x",
+            },
+            "body": {
+                "intent": "TASK",
+                "content": "stale",
+            },
+        }
+        signed = sign_envelope_ed25519(envelope, _TEST_PRIVATE_KEY)
+        headers = {DEFAULT_HEADER: json.dumps(signed)}
+        ok, env, reason = verify_http_envelope(headers, _registry(), strict_ttl=True)
+        self.assertFalse(ok)
+        self.assertEqual(reason, "ttl-expired")
+
+    def test_round_trip_strict_ttl_disabled(self):
+        # Same expired envelope but strict_ttl=False → signature still valid
+        past_ms = int(time.time() * 1000) - 120_000
+        envelope = {
+            "header": {
+                "version": "7h3/0.1",
+                "messageId": "expired-msg-2",
+                "timestampMs": past_ms,
+                "ttlMs": 1_000,
+                "sender": _SENDER,
+                "nonce": "nonce-y",
+            },
+            "body": {
+                "intent": "TASK",
+                "content": "stale but skip ttl check",
+            },
+        }
+        signed = sign_envelope_ed25519(envelope, _TEST_PRIVATE_KEY)
+        headers = {DEFAULT_HEADER: json.dumps(signed)}
+        ok, env, reason = verify_http_envelope(headers, _registry(), strict_ttl=False)
+        self.assertTrue(ok)
+        self.assertIsNone(reason)
+
+    def test_custom_header_name(self):
+        unsigned = _make_valid_envelope()
+        custom_hdr = "x-my-agent-envelope"
+        headers = sign_http_request(unsigned, _TEST_PRIVATE_KEY, header_name=custom_hdr)
+        self.assertIn(custom_hdr, headers)
+        ok, env, reason = verify_http_envelope(headers, _registry(), header_name=custom_hdr)
+        self.assertTrue(ok)
+        self.assertIsNone(reason)
+
+
+class TestBuildSignedRequestHeaders(unittest.TestCase):
+    """7. build_signed_request_headers produces correct header key."""
+
+    def test_default_header_key_present(self):
+        headers = build_signed_request_headers(
+            sender=_SENDER,
+            private_key=_TEST_PRIVATE_KEY,
+            content="ping",
+        )
+        self.assertIn(DEFAULT_HEADER, headers)
+
+    def test_custom_header_key(self):
+        custom = "x-aip-envelope"
+        headers = build_signed_request_headers(
+            sender=_SENDER,
+            private_key=_TEST_PRIVATE_KEY,
+            content="ping",
+            header_name=custom,
+        )
+        self.assertIn(custom, headers)
+        self.assertNotIn(DEFAULT_HEADER, headers)
+
+    def test_header_value_is_valid_json_envelope(self):
+        headers = build_signed_request_headers(
+            sender=_SENDER,
+            private_key=_TEST_PRIVATE_KEY,
+            content="check me",
+            ttl_ms=30_000,
+        )
+        raw = headers[DEFAULT_HEADER]
+        envelope = json.loads(raw)
+        self.assertEqual(envelope["header"]["sender"], _SENDER)
+        self.assertEqual(envelope["body"]["content"], "check me")
+        self.assertEqual(envelope["signature"]["alg"], "ED25519")
+
+    def test_round_trip_verify(self):
+        headers = build_signed_request_headers(
+            sender=_SENDER,
+            private_key=_TEST_PRIVATE_KEY,
+            content="full round trip",
+            recipient="agent.receiver",
+        )
+        ok, env, reason = verify_http_envelope(headers, _registry())
+        self.assertTrue(ok)
+        self.assertIsNone(reason)
+        self.assertEqual(env["body"]["content"], "full round trip")
+
+    def test_recipient_is_included_when_provided(self):
+        headers = build_signed_request_headers(
+            sender=_SENDER,
+            private_key=_TEST_PRIVATE_KEY,
+            content="msg",
+            recipient="agent.b",
+        )
+        envelope = json.loads(headers[DEFAULT_HEADER])
+        self.assertEqual(envelope["header"].get("recipient"), "agent.b")
+
+
+if __name__ == "__main__":
+    unittest.main()