7h3-protocol 0.4.0__py3-none-any.whl

7h3_protocol-0.4.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+protocol_7h3/__init__.py,sha256=VEk1DMHva_UcGLKA-iHPrSYJqFD5tpUm6C5fmYSR7QA,1191
+protocol_7h3/http.py,sha256=i7tMsJpBqej1g9tpC6P52YF5PduFMO3sOsCbbx2CRP4,6726
+protocol_7h3/keys.py,sha256=HRE2jGBRRF9s7gt3biYAteeB3OVPYwUZPXhUH2uCsrM,5476
+protocol_7h3/protocol.py,sha256=6ZJwJ2RcNhMqpkIGcON_OwaATn2kccXPfUH_xgc_riY,16833
+protocol_7h3/queue.py,sha256=r_Ge8YEBIsRWwHpp-nlkAvAmuUkJDb1C3FeRJ6nJCiM,3504
+protocol_7h3/webhook.py,sha256=hVeFSgAbFZ9kjxFwM7bVlvQAxTpwnd-dUzgKSVmbVwE,3780
+7h3_protocol-0.4.0.dist-info/METADATA,sha256=0bkaScqbrNB20vHuXn0smuw3aBUzj20c6rUzXCMQ21Y,1914
+7h3_protocol-0.4.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+7h3_protocol-0.4.0.dist-info/RECORD,,

7h3_protocol-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

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

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

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")}

protocol_7h3/protocol.py

@@ -0,0 +1,525 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, TypedDict
+
+# ---------------------------------------------------------------------------
+# Optional native Ed25519 backend — try cryptography, then PyNaCl
+# ---------------------------------------------------------------------------
+
+try:
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+        Ed25519PrivateKey,
+        Ed25519PublicKey,
+    )
+
+    _HAS_CRYPTOGRAPHY = True
+except Exception:
+    _HAS_CRYPTOGRAPHY = False
+
+try:
+    import nacl.signing as _nacl_signing  # type: ignore[import]
+
+    _HAS_NACL = True
+except Exception:
+    _HAS_NACL = False
+
+# ---------------------------------------------------------------------------
+# Pure-Python Ed25519 fallback (no external dependencies)
+#
+# Uses extended twisted Edwards coordinates (X:Y:Z:T) to eliminate the
+# expensive field inversion from the inner loop — inversion runs once at
+# point compression only. ~10–50 ms/op in CPython; correct for conformance
+# testing. Install 'cryptography' for production-grade performance.
+#
+# Based on the reference implementation: https://ed25519.cr.yp.to/software.html
+# ---------------------------------------------------------------------------
+
+_P = 2**255 - 19
+_L = 2**252 + 27742317777372353535851937790883648493
+_D = -121665 * pow(121666, _P - 2, _P) % _P
+_SQRT_M1 = pow(2, (_P - 1) // 4, _P)
+
+# Base point G in extended coordinates (X:Y:Z:T)
+_GY = 4 * pow(5, _P - 2, _P) % _P
+_GX_SQ = (_GY * _GY - 1) * pow(_D * _GY * _GY + 1, _P - 2, _P) % _P
+_GX = pow(_GX_SQ, (_P + 3) // 8, _P)
+if (_GX * _GX - _GX_SQ) % _P != 0:
+    _GX = _GX * _SQRT_M1 % _P
+if _GX & 1:
+    _GX = _P - _GX
+_G_BASE = (_GX, _GY, 1, _GX * _GY % _P)
+
+
+def _point_add(P: tuple, Q: tuple) -> tuple:
+    A = (P[1] - P[0]) * (Q[1] - Q[0]) % _P
+    B = (P[1] + P[0]) * (Q[1] + Q[0]) % _P
+    C = 2 * P[3] * Q[3] * _D % _P
+    D_ = 2 * P[2] * Q[2] % _P
+    E = B - A
+    F = D_ - C
+    G_ = D_ + C
+    H = B + A
+    return (E * F % _P, G_ * H % _P, F * G_ % _P, E * H % _P)
+
+
+def _point_mul(s: int, P: tuple) -> tuple:
+    Q: tuple = (0, 1, 1, 0)  # neutral element
+    while s > 0:
+        if s & 1:
+            Q = _point_add(Q, P)
+        P = _point_add(P, P)
+        s >>= 1
+    return Q
+
+
+def _compress(P: tuple) -> bytes:
+    zi = pow(P[2], _P - 2, _P)
+    x = P[0] * zi % _P
+    y = P[1] * zi % _P
+    return int.to_bytes(y | ((x & 1) << 255), 32, "little")
+
+
+def _decompress(b: bytes) -> Optional[tuple]:
+    y = int.from_bytes(b, "little")
+    sign = y >> 255
+    y &= (1 << 255) - 1
+    x2 = (y * y - 1) * pow(_D * y * y + 1, _P - 2, _P) % _P
+    if x2 == 0:
+        return (0, y, 1, 0) if sign == 0 else None
+    x = pow(x2, (_P + 3) // 8, _P)
+    if (x * x - x2) % _P != 0:
+        x = x * _SQRT_M1 % _P
+    if (x * x - x2) % _P != 0:
+        return None
+    if x & 1 != sign:
+        x = _P - x
+    return (x, y, 1, x * y % _P)
+
+
+def _py_ed25519_sign(seed: bytes, message: bytes) -> bytes:
+    h = hashlib.sha512(seed).digest()
+    a_bytes = bytearray(h[:32])
+    a_bytes[0] &= 248
+    a_bytes[31] &= 127
+    a_bytes[31] |= 64
+    a = int.from_bytes(a_bytes, "little")
+    prefix = h[32:]
+    A = _compress(_point_mul(a, _G_BASE))
+    r = int.from_bytes(hashlib.sha512(prefix + message).digest(), "little") % _L
+    R = _compress(_point_mul(r, _G_BASE))
+    S = (r + int.from_bytes(hashlib.sha512(R + A + message).digest(), "little") * a) % _L
+    return R + int.to_bytes(S, 32, "little")
+
+
+def _py_ed25519_verify(pub_bytes: bytes, message: bytes, sig: bytes) -> bool:
+    if len(sig) != 64 or len(pub_bytes) != 32:
+        return False
+    A = _decompress(pub_bytes)
+    if A is None:
+        return False
+    R_pt = _decompress(sig[:32])
+    if R_pt is None:
+        return False
+    s = int.from_bytes(sig[32:], "little")
+    if s >= _L:
+        return False
+    h = int.from_bytes(hashlib.sha512(sig[:32] + pub_bytes + message).digest(), "little")
+    sB = _point_mul(s, _G_BASE)
+    hA = _point_mul(h, A)
+    return _compress(sB) == _compress(_point_add(R_pt, hA))
+
+
+# ---------------------------------------------------------------------------
+# DER key extraction helpers
+#
+# WebCrypto exports Ed25519 keys as PKCS8 (private) and SPKI (public) DER.
+# Both formats have a fixed structure for Ed25519 with known byte offsets:
+#
+#   PKCS8 v0 (48 bytes):
+#     30 2e 02 01 00 30 05 06 03 2b 65 70 04 22 04 20 [32-byte seed]
+#
+#   SPKI (44 bytes):
+#     30 2a 30 05 06 03 2b 65 70 03 21 00 [32-byte public key]
+# ---------------------------------------------------------------------------
+
+# fmt: off
+_PKCS8_ED25519_LEN = 48  # 30 2e 02 01 00 30 05 06 03 2b 65 70 04 22 04 20 [32-byte seed]
+_SPKI_ED25519_LEN  = 44  # 30 2a 30 05 06 03 2b 65 70 03 21 00 [32-byte public key]
+# fmt: on
+
+
+def _seed_from_pkcs8(pkcs8_der: bytes) -> bytes:
+    if len(pkcs8_der) != 48:
+        raise ValueError(
+            f"Ed25519 PKCS8 DER must be 48 bytes, got {len(pkcs8_der)}. "
+            "Ensure the key was exported with SubtleCrypto.exportKey('pkcs8', key)."
+        )
+    return pkcs8_der[16:48]
+
+
+def _pubkey_from_spki(spki_der: bytes) -> bytes:
+    if len(spki_der) != 44:
+        raise ValueError(
+            f"Ed25519 SPKI DER must be 44 bytes, got {len(spki_der)}. "
+            "Ensure the key was exported with SubtleCrypto.exportKey('spki', key)."
+        )
+    return spki_der[12:44]
+
+
+# ---------------------------------------------------------------------------
+# Protocol types
+# ---------------------------------------------------------------------------
+
+
+class ProtocolHeader(TypedDict, total=False):
+    version: str
+    messageId: str
+    timestampMs: int
+    ttlMs: int
+    sender: str
+    recipient: str
+    nonce: str
+
+
+class ProtocolBody(TypedDict, total=False):
+    intent: str
+    content: str
+    capability: str
+    correlationId: str
+
+
+class ProtocolSignature(TypedDict):
+    alg: str
+    keyId: str
+    value: str
+
+
+class ProtocolEnvelope(TypedDict, total=False):
+    header: ProtocolHeader
+    body: ProtocolBody
+    signature: ProtocolSignature
+
+
+@dataclass(frozen=True)
+class ProtocolDiagnostic:
+    level: str
+    message: str
+
+
+# ---------------------------------------------------------------------------
+# Utility
+# ---------------------------------------------------------------------------
+
+
+def _json_string(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+
+def _base64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
+
+
+def _base64url_decode(value: str) -> bytes:
+    padding = "=" * ((4 - (len(value) % 4)) % 4)
+    return base64.urlsafe_b64decode(value + padding)
+
+
+# ---------------------------------------------------------------------------
+# Canonicalization
+# ---------------------------------------------------------------------------
+
+
+def canonicalize_envelope(envelope: Dict[str, Any]) -> str:
+    header = envelope["header"]
+    body = envelope["body"]
+
+    body_parts = []
+    if "capability" in body and body["capability"] is not None:
+        body_parts.append(f'"capability":{_json_string(body["capability"])}')
+    body_parts.append(f'"content":{_json_string(body["content"])}')
+    if "correlationId" in body and body["correlationId"] is not None:
+        body_parts.append(f'"correlationId":{_json_string(body["correlationId"])}')
+    body_parts.append(f'"intent":{_json_string(body["intent"])}')
+
+    header_parts = [
+        f'"messageId":{_json_string(header["messageId"])}',
+        f'"nonce":{_json_string(header["nonce"])}',
+    ]
+    if "recipient" in header and header["recipient"] is not None:
+        header_parts.append(f'"recipient":{_json_string(header["recipient"])}')
+    header_parts.extend(
+        [
+            f'"sender":{_json_string(header["sender"])}',
+            f'"timestampMs":{int(header["timestampMs"])}',
+            f'"ttlMs":{int(header["ttlMs"])}',
+            f'"version":{_json_string(header["version"])}',
+        ]
+    )
+
+    return (
+        f'{{"body":{{{",".join(body_parts)}}},"header":{{{",".join(header_parts)}}}}}'
+    )
+
+
+# ---------------------------------------------------------------------------
+# HMAC-SHA256 (HS256)
+# ---------------------------------------------------------------------------
+
+
+def sign_canonical_payload_hmac(canonical_payload: str, secret: str) -> str:
+    digest = hmac.new(
+        secret.encode("utf-8"), canonical_payload.encode("utf-8"), hashlib.sha256
+    ).digest()
+    return _base64url(digest)
+
+
+def verify_canonical_payload_hmac(
+    canonical_payload: str, signature: str, secret: str
+) -> bool:
+    expected = sign_canonical_payload_hmac(canonical_payload, secret)
+    return hmac.compare_digest(signature, expected)
+
+
+# ---------------------------------------------------------------------------
+# Ed25519 — tries cryptography → PyNaCl → pure-Python in order
+# ---------------------------------------------------------------------------
+
+
+def sign_canonical_payload_ed25519(
+    canonical_payload: str, private_key_pkcs8_base64url: str
+) -> str:
+    private_der = _base64url_decode(private_key_pkcs8_base64url)
+    msg = canonical_payload.encode("utf-8")
+
+    if _HAS_CRYPTOGRAPHY:
+        key = serialization.load_der_private_key(private_der, password=None)
+        if not isinstance(key, Ed25519PrivateKey):
+            raise ValueError("DER key is not an Ed25519 private key")
+        return _base64url(key.sign(msg))
+
+    if _HAS_NACL:
+        seed = _seed_from_pkcs8(private_der)
+        sk = _nacl_signing.SigningKey(seed)
+        return _base64url(bytes(sk.sign(msg).signature))
+
+    # Pure-Python fallback
+    seed = _seed_from_pkcs8(private_der)
+    return _base64url(_py_ed25519_sign(seed, msg))
+
+
+def verify_canonical_payload_ed25519(
+    canonical_payload: str, signature: str, public_key_spki_base64url: str
+) -> bool:
+    public_der = _base64url_decode(public_key_spki_base64url)
+    msg = canonical_payload.encode("utf-8")
+    sig_bytes = _base64url_decode(signature)
+
+    if _HAS_CRYPTOGRAPHY:
+        try:
+            key = serialization.load_der_public_key(public_der)
+            if not isinstance(key, Ed25519PublicKey):
+                return False
+            key.verify(sig_bytes, msg)
+            return True
+        except Exception:
+            return False
+
+    if _HAS_NACL:
+        try:
+            pub_bytes = _pubkey_from_spki(public_der)
+            vk = _nacl_signing.VerifyKey(pub_bytes)
+            vk.verify(msg, sig_bytes)
+            return True
+        except Exception:
+            return False
+
+    # Pure-Python fallback
+    try:
+        pub_bytes = _pubkey_from_spki(public_der)
+        return _py_ed25519_verify(pub_bytes, msg, sig_bytes)
+    except Exception:
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Envelope-level sign/verify helpers
+# ---------------------------------------------------------------------------
+
+
+def sign_envelope_hmac(
+    envelope: Dict[str, Any], secret: str, key_id: str = "python-dev-key"
+) -> Dict[str, Any]:
+    canonical = canonicalize_envelope(envelope)
+    signature = sign_canonical_payload_hmac(canonical, secret)
+    return {
+        "header": dict(envelope["header"]),
+        "body": dict(envelope["body"]),
+        "signature": {"alg": "HS256", "keyId": key_id, "value": signature},
+    }
+
+
+def verify_envelope_hmac(envelope: Dict[str, Any], secret: str) -> bool:
+    signature = envelope.get("signature")
+    if not signature:
+        return False
+    if signature.get("alg") != "HS256":
+        return False
+    unsigned = {"header": envelope["header"], "body": envelope["body"]}
+    canonical = canonicalize_envelope(unsigned)
+    return verify_canonical_payload_hmac(canonical, signature.get("value", ""), secret)
+
+
+def sign_envelope_ed25519(
+    envelope: Dict[str, Any],
+    private_key_pkcs8_base64url: str,
+    key_id: str = "python-ed25519-key",
+) -> Dict[str, Any]:
+    canonical = canonicalize_envelope(envelope)
+    signature = sign_canonical_payload_ed25519(canonical, private_key_pkcs8_base64url)
+    return {
+        "header": dict(envelope["header"]),
+        "body": dict(envelope["body"]),
+        "signature": {"alg": "ED25519", "keyId": key_id, "value": signature},
+    }
+
+
+def verify_envelope_ed25519(
+    envelope: Dict[str, Any], public_key_spki_base64url: str
+) -> bool:
+    signature = envelope.get("signature")
+    if not signature:
+        return False
+    if signature.get("alg") != "ED25519":
+        return False
+    unsigned = {"header": envelope["header"], "body": envelope["body"]}
+    canonical = canonicalize_envelope(unsigned)
+    return verify_canonical_payload_ed25519(
+        canonical, signature.get("value", ""), public_key_spki_base64url
+    )
+
+
+# ---------------------------------------------------------------------------
+# Wire encode/decode
+# ---------------------------------------------------------------------------
+
+
+def encode_envelope_compact(envelope: Dict[str, Any]) -> str:
+    header = envelope["header"]
+    body = envelope["body"]
+    compact: Dict[str, Any] = {
+        "v": header["version"],
+        "mid": header["messageId"],
+        "ts": header["timestampMs"],
+        "ttl": header["ttlMs"],
+        "s": header["sender"],
+        "n": header["nonce"],
+        "i": body["intent"],
+        "c": body["content"],
+    }
+    if "recipient" in header and header["recipient"] is not None:
+        compact["r"] = header["recipient"]
+    if "capability" in body and body["capability"] is not None:
+        compact["cap"] = body["capability"]
+    if "correlationId" in body and body["correlationId"] is not None:
+        compact["cid"] = body["correlationId"]
+
+    signature = envelope.get("signature")
+    if signature:
+        compact["sig"] = {
+            "a": signature.get("alg", "HS256"),
+            "k": signature["keyId"],
+            "v": signature["value"],
+        }
+
+    return _json_string(compact)
+
+
+def decode_envelope(raw: str) -> Dict[str, Any]:
+    parsed = json.loads(raw)
+    if "header" in parsed and "body" in parsed:
+        return parsed
+
+    if parsed.get("v") != "7h3/0.1" or "mid" not in parsed or "i" not in parsed:
+        raise ValueError("Envelope JSON shape is not recognized")
+
+    header: Dict[str, Any] = {
+        "version": parsed["v"],
+        "messageId": parsed["mid"],
+        "timestampMs": parsed["ts"],
+        "ttlMs": parsed["ttl"],
+        "sender": parsed["s"],
+        "nonce": parsed["n"],
+    }
+    if "r" in parsed:
+        header["recipient"] = parsed["r"]
+
+    body: Dict[str, Any] = {
+        "intent": parsed["i"],
+        "content": parsed["c"],
+    }
+    if "cap" in parsed:
+        body["capability"] = parsed["cap"]
+    if "cid" in parsed:
+        body["correlationId"] = parsed["cid"]
+
+    envelope: Dict[str, Any] = {"header": header, "body": body}
+    if parsed.get("sig"):
+        envelope["signature"] = {
+            "alg": parsed["sig"].get("a", "HS256"),
+            "keyId": parsed["sig"]["k"],
+            "value": parsed["sig"]["v"],
+        }
+    return envelope
+
+
+# ---------------------------------------------------------------------------
+# Envelope validation
+# ---------------------------------------------------------------------------
+
+
+def validate_envelope(
+    envelope: Dict[str, Any], now_ms: Optional[int] = None
+) -> list[ProtocolDiagnostic]:
+    header = envelope["header"]
+    body = envelope["body"]
+    current = int(now_ms if now_ms is not None else 0)
+    diagnostics: list[ProtocolDiagnostic] = []
+
+    if header.get("version") != "7h3/0.1":
+        diagnostics.append(
+            ProtocolDiagnostic(
+                level="error",
+                message=f"Unsupported protocol version '{header.get('version')}'",
+            )
+        )
+    if not str(header.get("messageId", "")).strip():
+        diagnostics.append(
+            ProtocolDiagnostic(level="error", message="Missing messageId")
+        )
+    if not str(header.get("sender", "")).strip():
+        diagnostics.append(
+            ProtocolDiagnostic(level="error", message="Missing sender identity")
+        )
+    if int(header.get("ttlMs", 0)) <= 0:
+        diagnostics.append(
+            ProtocolDiagnostic(level="error", message="ttlMs must be greater than zero")
+        )
+
+    if now_ms is not None:
+        if int(header.get("timestampMs", 0)) + int(header.get("ttlMs", 0)) < current:
+            diagnostics.append(
+                ProtocolDiagnostic(level="error", message="Message TTL expired")
+            )
+
+    if not str(body.get("content", "")).strip():
+        diagnostics.append(
+            ProtocolDiagnostic(level="warning", message="Empty content payload")
+        )
+
+    return diagnostics

protocol_7h3/queue.py

@@ -0,0 +1,118 @@
+"""Queue message binding for 7h3 Protocol — Kafka/SQS/Pub-Sub/RabbitMQ."""
+from __future__ import annotations
+
+import json
+import secrets
+import time
+from typing import Any, Dict, List, Optional
+
+QUEUE_DEFAULT_TTL_MS = 3_600_000  # 1 hour
+
+
+def _create_envelope(
+    sender: str,
+    content: str,
+    ttl_ms: int,
+    *,
+    recipient: Optional[str] = None,
+    intent: str = "TASK",
+) -> Dict[str, Any]:
+    """Build a bare (unsigned) protocol envelope dict."""
+    now_ms = int(time.time() * 1000)
+    message_id = secrets.token_hex(16)
+    nonce = secrets.token_hex(8)
+    header: Dict[str, Any] = {
+        "version": "7h3/0.1",
+        "messageId": message_id,
+        "timestampMs": now_ms,
+        "ttlMs": ttl_ms,
+        "sender": sender,
+        "nonce": nonce,
+    }
+    if recipient is not None:
+        header["recipient"] = recipient
+
+    body: Dict[str, Any] = {
+        "intent": intent,
+        "content": content,
+    }
+    return {"header": header, "body": body}
+
+
+def sign_queue_message(
+    payload: Any,
+    private_key: str,
+    sender: str,
+    *,
+    recipient: Optional[str] = None,
+    ttl_ms: int = QUEUE_DEFAULT_TTL_MS,
+) -> str:
+    """
+    Sign a payload for queue transit.
+    Returns a JSON string: {"envelope": {...}, "payload": payload}
+    """
+    from .protocol import sign_envelope_ed25519
+
+    content = payload if isinstance(payload, str) else json.dumps(payload, separators=(",", ":"))
+    envelope = _create_envelope(
+        sender=sender,
+        content=content,
+        ttl_ms=ttl_ms,
+        recipient=recipient,
+    )
+    signed = sign_envelope_ed25519(envelope, private_key)
+    return json.dumps({"envelope": signed, "payload": payload}, separators=(",", ":"))
+
+
+def verify_queue_message(message: str, public_key: str) -> Dict[str, Any]:
+    """
+    Verify and unwrap a queue message.
+    Returns {"payload": Any, "envelope": dict}.
+    Raises ValueError on failure.
+    """
+    from .protocol import verify_envelope_ed25519, validate_envelope
+
+    try:
+        wrapper = json.loads(message)
+    except Exception as e:
+        raise ValueError(f"7h3: malformed queue message: {e}") from e
+
+    envelope = wrapper.get("envelope")
+    payload = wrapper.get("payload")
+    if not envelope or not isinstance(envelope, dict):
+        raise ValueError("7h3: missing envelope in queue message")
+
+    # validate_envelope returns list[ProtocolDiagnostic] (dataclass objects)
+    diags = validate_envelope(envelope)
+    errors = [d for d in diags if d.level == "error"]
+    if errors:
+        raise ValueError(
+            f"7h3: envelope validation failed: {'; '.join(d.message for d in errors)}"
+        )
+
+    valid = verify_envelope_ed25519(envelope, public_key)
+    if not valid:
+        raise ValueError("7h3: invalid signature on queue message")
+
+    return {"payload": payload, "envelope": envelope}
+
+
+def verify_queue_batch(
+    messages: List[str],
+    public_key: str,
+) -> List[Dict[str, Any]]:
+    """
+    Verify a batch of queue messages without throwing.
+    Each result is {"ok": True, "payload": ..., "envelope": ...} or
+    {"ok": False, "raw": ..., "error": "..."}.
+    """
+    results = []
+    for msg in messages:
+        try:
+            result = verify_queue_message(msg, public_key)
+            results.append(
+                {"ok": True, "payload": result["payload"], "envelope": result["envelope"]}
+            )
+        except Exception as e:
+            results.append({"ok": False, "raw": msg, "error": str(e)})
+    return results

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)