@7h3/protocol 0.5.0 → 0.5.1

package/sdk/python/protocol_7h3/http.py

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

package/sdk/python/protocol_7h3/keys.py

@@ -1,149 +0,0 @@
-"""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")}

package/sdk/python/protocol_7h3/pq.py

@@ -1,244 +0,0 @@
-"""
-Post-quantum signatures for 7h3 Protocol.
-
-Provides ML-DSA-65 and ML-DSA-87 (formerly Dilithium3 / Dilithium5) via
-the dilithium-py pure-Python library.
-
-Install the dependency:
-    pip install dilithium-py
-
-Mapping:
-    ML-DSA-44  ≈  Dilithium2  (security category 2)
-    ML-DSA-65  ≈  Dilithium3  (security category 3)
-    ML-DSA-87  ≈  Dilithium5  (security category 5)
-"""
-
-from __future__ import annotations
-
-import base64
-import json
-import os
-import time
-from typing import Any, Dict, Optional, Tuple
-
-# ---------------------------------------------------------------------------
-# Optional dilithium-py backend
-# ---------------------------------------------------------------------------
-
-try:
-    from dilithium_py.dilithium import Dilithium2, Dilithium3, Dilithium5  # type: ignore[import]
-
-    _HAS_DILITHIUM = True
-except ImportError:
-    _HAS_DILITHIUM = False
-
-
-def _require_dilithium() -> None:
-    if not _HAS_DILITHIUM:
-        raise ImportError(
-            "dilithium-py is required for post-quantum signatures.\n"
-            "Install it with:\n\n"
-            "    pip install dilithium-py\n"
-        )
-
-
-# ---------------------------------------------------------------------------
-# Base64url helpers
-# ---------------------------------------------------------------------------
-
-
-def _to_b64url(data: bytes) -> str:
-    """Encode bytes to base64url without padding."""
-    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
-
-
-def _from_b64url(value: str) -> bytes:
-    """Decode base64url (with or without padding)."""
-    padded = value + "=" * ((-len(value)) % 4)
-    return base64.urlsafe_b64decode(padded)
-
-
-# ---------------------------------------------------------------------------
-# Level → Dilithium implementation mapping
-# ---------------------------------------------------------------------------
-
-_LEVEL_MAP = {
-    44: "Dilithium2",
-    65: "Dilithium3",
-    87: "Dilithium5",
-}
-
-
-def _get_impl(level: int) -> Any:
-    """Return the Dilithium implementation for the given ML-DSA level."""
-    _require_dilithium()
-    if level == 44:
-        return Dilithium2
-    if level == 65:
-        return Dilithium3
-    if level == 87:
-        return Dilithium5
-    raise ValueError(f"Unsupported ML-DSA level: {level}. Use 44, 65, or 87.")
-
-
-def _alg_name(level: int) -> str:
-    if level == 44:
-        return "ML-DSA-44"
-    if level == 65:
-        return "ML-DSA-65"
-    if level == 87:
-        return "ML-DSA-87"
-    raise ValueError(f"Unsupported ML-DSA level: {level}")
-
-
-# ---------------------------------------------------------------------------
-# Canonicalization (mirrors TypeScript canonicalizeEnvelope)
-# ---------------------------------------------------------------------------
-
-
-def _canonicalize_envelope(envelope: Dict[str, Any]) -> str:
-    """Produce the canonical JSON string for signing (matches TS implementation)."""
-    header = envelope["header"]
-    body = envelope["body"]
-
-    # Build canonical header (sorted keys, only defined fields)
-    header_parts: list[str] = [
-        f'"messageId":{json.dumps(header["messageId"])}',
-        f'"nonce":{json.dumps(header["nonce"])}',
-    ]
-    if header.get("recipient") is not None:
-        header_parts.append(f'"recipient":{json.dumps(header["recipient"])}')
-    header_parts.append(f'"sender":{json.dumps(header["sender"])}')
-    header_parts.append(f'"timestampMs":{header["timestampMs"]}')
-    header_parts.append(f'"ttlMs":{header["ttlMs"]}')
-    header_parts.append(f'"version":{json.dumps(header["version"])}')
-    canonical_header = "{" + ",".join(header_parts) + "}"
-
-    # Build canonical body (sorted keys, only defined fields)
-    body_parts: list[str] = []
-    if body.get("capability") is not None:
-        body_parts.append(f'"capability":{json.dumps(body["capability"])}')
-    body_parts.append(f'"content":{json.dumps(body["content"])}')
-    if body.get("correlationId") is not None:
-        body_parts.append(f'"correlationId":{json.dumps(body["correlationId"])}')
-    body_parts.append(f'"intent":{json.dumps(body["intent"])}')
-    canonical_body = "{" + ",".join(body_parts) + "}"
-
-    return '{"body":' + canonical_body + ',"header":' + canonical_header + "}"
-
-
-# ---------------------------------------------------------------------------
-# Public API
-# ---------------------------------------------------------------------------
-
-
-def generate_ml_dsa_keypair(level: int = 65) -> Tuple[str, str]:
-    """
-    Generate a fresh ML-DSA keypair.
-
-    Parameters
-    ----------
-    level : int
-        Security level: 44 (≈ ML-DSA-44), 65 (≈ ML-DSA-65), 87 (≈ ML-DSA-87).
-        Default is 65.
-
-    Returns
-    -------
-    (public_key_b64url, secret_key_b64url) : tuple[str, str]
-        Both keys encoded as base64url without padding.
-    """
-    impl = _get_impl(level)
-    pk, sk = impl.keygen()
-    return _to_b64url(pk), _to_b64url(sk)
-
-
-def sign_envelope_pq(
-    envelope_dict: Dict[str, Any],
-    secret_key_b64url: str,
-    level: int = 65,
-) -> Dict[str, Any]:
-    """
-    Sign a protocol envelope dict with ML-DSA.
-
-    Parameters
-    ----------
-    envelope_dict : dict
-        Envelope with 'header' and 'body' keys. Any existing 'signature' is ignored.
-    secret_key_b64url : str
-        Base64url-encoded secret key (from generate_ml_dsa_keypair).
-    level : int
-        ML-DSA security level (44, 65, or 87). Default 65.
-
-    Returns
-    -------
-    dict
-        Copy of envelope_dict with 'signature' populated.
-    """
-    impl = _get_impl(level)
-    alg = _alg_name(level)
-
-    # Strip existing signature for canonicalization
-    unsigned = {k: v for k, v in envelope_dict.items() if k != "signature"}
-    canonical = _canonicalize_envelope(unsigned)
-    message = canonical.encode("utf-8")
-
-    sk = _from_b64url(secret_key_b64url)
-    sig_bytes = impl.sign(sk, message)
-    sig_b64url = _to_b64url(sig_bytes)
-    key_id = secret_key_b64url[:16]
-
-    return {
-        **unsigned,
-        "signature": {
-            "alg": alg,
-            "keyId": key_id,
-            "value": sig_b64url,
-        },
-    }
-
-
-def verify_envelope_pq(
-    envelope_dict: Dict[str, Any],
-    public_key_b64url: str,
-    level: Optional[int] = None,
-) -> bool:
-    """
-    Verify a ML-DSA-signed protocol envelope.
-
-    Parameters
-    ----------
-    envelope_dict : dict
-        Signed envelope with 'signature' key.
-    public_key_b64url : str
-        Base64url-encoded public key.
-    level : int or None
-        ML-DSA security level. If None, inferred from signature.alg field.
-
-    Returns
-    -------
-    bool
-        True if the signature is valid, False otherwise.
-    """
-    sig = envelope_dict.get("signature")
-    if not sig:
-        return False
-
-    alg: str = sig.get("alg", "")
-    if level is None:
-        # Infer level from alg field
-        _alg_to_level = {"ML-DSA-44": 44, "ML-DSA-65": 65, "ML-DSA-87": 87}
-        level = _alg_to_level.get(alg)
-        if level is None:
-            return False
-
-    impl = _get_impl(level)
-    unsigned = {k: v for k, v in envelope_dict.items() if k != "signature"}
-    canonical = _canonicalize_envelope(unsigned)
-    message = canonical.encode("utf-8")
-
-    pk = _from_b64url(public_key_b64url)
-    try:
-        sig_bytes = _from_b64url(sig["value"])
-        return bool(impl.verify(pk, message, sig_bytes))
-    except Exception:
-        return False