cyphra 0.1.0__py3-none-any.whl

cyphra/__init__.py

@@ -0,0 +1,15 @@
+"""Cyphra: a hybrid post-quantum, zero-knowledge messaging platform."""
+
+from cyphra.crypto.engine import CryptoEngine
+from cyphra.client import CyphraClient
+from cyphra.models import EncryptedEnvelope, PreKeyBundle, PrivateIdentityMaterial
+from cyphra.storage.database import DatabaseManager
+
+__all__ = [
+    "CryptoEngine",
+    "CyphraClient",
+    "DatabaseManager",
+    "EncryptedEnvelope",
+    "PreKeyBundle",
+    "PrivateIdentityMaterial",
+]

cyphra/cli.py

@@ -0,0 +1,238 @@
+"""Operational entry point for the relay."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import getpass
+import hashlib
+import logging
+import re
+import ssl
+import sys
+from pathlib import Path
+
+from cyphra.client import CyphraClient
+from cyphra.constants import DEFAULT_BROKER_URL
+from cyphra.crypto.engine import CryptoEngine
+from cyphra.exceptions import BrokerError, ConfigurationError, CyphraError
+from cyphra.network.client import BrokerTransport
+from cyphra.network.http_client import HttpBrokerClient
+from cyphra.network.websocket_broker import WebSocketBroker
+from cyphra.storage.database import DatabaseManager
+
+
+def server_main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(description="Run the Cyphra zero-knowledge relay")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8765)
+    parser.add_argument("--cert", help="PEM server certificate")
+    parser.add_argument("--key", dest="key_file", help="PEM private key")
+    parser.add_argument(
+        "--insecure-dev",
+        action="store_true",
+        help="allow ws:// for local development; never use this in production",
+    )
+    parser.add_argument("--log-level", default="INFO", choices=["DEBUG", "INFO", "WARNING", "ERROR"])
+    args = parser.parse_args(argv)
+    logging.basicConfig(level=getattr(logging, args.log_level))
+
+    if bool(args.cert) != bool(args.key_file):
+        parser.error("--cert and --key must be supplied together")
+    if not args.insecure_dev and not args.cert:
+        parser.error("TLS is required; provide --cert/--key or explicitly pass --insecure-dev")
+
+    tls_context: ssl.SSLContext | None = None
+    if args.cert:
+        tls_context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+        tls_context.minimum_version = ssl.TLSVersion.TLSv1_3
+        tls_context.load_cert_chain(args.cert, args.key_file)
+
+    broker = WebSocketBroker(
+        args.host,
+        args.port,
+        ssl_context=tls_context,
+        allow_insecure_dev=args.insecure_dev,
+    )
+    try:
+        asyncio.run(broker.serve_forever())
+    except KeyboardInterrupt:
+        pass
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Interactive two-user terminal chat entry point."""
+
+    parser = argparse.ArgumentParser(prog="cyphra", description="Cyphra encrypted terminal chat")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    chat_parser = subparsers.add_parser("chat", help="join a two-person realtime chat")
+    chat_parser.add_argument("--name", required=True, help="local display name and default database name")
+    chat_parser.add_argument("--db", type=Path, help="encrypted identity database path")
+    args = parser.parse_args(argv)
+
+    try:
+        asyncio.run(_chat(args))
+    except KeyboardInterrupt:
+        print("\nChat ended.")
+    except EOFError:
+        print("\nChat ended.")
+    except (CyphraError, OSError, ValueError) as exc:
+        print(f"cyphra: {exc}", file=sys.stderr)
+
+
+async def _chat(args: argparse.Namespace) -> None:
+    name = args.name.strip() or "user"
+    safe_name = re.sub(r"[^A-Za-z0-9_-]+", "_", name).strip("_") or "user"
+    database_path = args.db or (Path.home() / ".cyphra" / f"{safe_name}.db")
+    passphrase = _prompt_database_passphrase(database_path)
+    database = DatabaseManager.from_passphrase(database_path, passphrase)
+    relay: WebSocketBroker | None = None
+    client: CyphraClient | None = None
+    receiver_task: asyncio.Task[None] | None = None
+    try:
+        engine = CryptoEngine()
+        try:
+            material = database.load_identity()
+        except ConfigurationError as exc:
+            if str(exc) != "no matching local identity is stored":
+                raise
+            CyphraClient.provision_identity(engine, database)
+            material = database.load_identity()
+
+        transport = HttpBrokerClient(DEFAULT_BROKER_URL)
+        client = CyphraClient(engine, database, transport)
+        await client.connect()
+        own_fingerprint = engine.identity_fingerprint(material.bundle)
+        print(f"Connected as {name}")
+        print(f"Your identity ID: {material.identity_id}")
+        print(f"Your fingerprint: {own_fingerprint}")
+        print("Connected people:")
+
+        peer_id = await _select_peer(transport, material.identity_id)
+        if peer_id is None:
+            return
+        peer_bundle, fingerprint = await client.discover_contact(peer_id)
+        print(f"Peer identity ID: {peer_id}")
+        print(f"Peer fingerprint: {fingerprint}")
+        print("Compare this fingerprint with your peer through a trusted channel before approving.")
+        try:
+            approval = await asyncio.to_thread(input, "Approve this peer? Type yes to continue: ")
+        except EOFError:
+            print("\nChat closed before peer approval.")
+            return
+        if approval.strip().lower() != "yes":
+            print("Peer was not approved. Chat closed.")
+            return
+        client.approve_contact(peer_bundle, fingerprint)
+
+        conversation_id = hashlib.sha256(
+            "\0".join(sorted((material.identity_id, peer_id))).encode("ascii")
+        ).hexdigest()
+        print(f"Chat with {peer_id[:12]} is ready. Type /quit to leave.")
+        receiver_task = asyncio.create_task(
+            _receive_chat_messages(client, peer_id),
+            name="cyphra-chat-receiver",
+        )
+        while True:
+            try:
+                line = await asyncio.to_thread(input, f"{name}> ")
+            except EOFError:
+                break
+            if line.strip() == "/quit":
+                break
+            if not line:
+                continue
+            try:
+                await client.send_message(peer_id, line.encode("utf-8"), conversation_id=conversation_id)
+                print(f"you> {line}")
+            except (CyphraError, ValueError) as exc:
+                print(f"Message not sent: {exc}")
+    finally:
+        if receiver_task is not None:
+            receiver_task.cancel()
+            try:
+                await receiver_task
+            except asyncio.CancelledError:
+                pass
+        if client is not None:
+            await client.close()
+        database.close()
+        if relay is not None:
+            await relay.close()
+
+
+async def _select_peer(
+    transport: BrokerTransport,
+    own_identity_id: str,
+) -> str | None:
+    while True:
+        peers = await transport.list_peers()
+        peers = tuple(peer_id for peer_id in peers if peer_id != own_identity_id)
+        print("\nConnected people")
+        print("----------------")
+        if not peers:
+            print("No one is connected yet.")
+            choice = await asyncio.to_thread(input, "[r]efresh or [q]uit: ")
+            if choice.strip().lower() == "q":
+                return None
+            continue
+        for index, peer_id in enumerate(peers, start=1):
+            print(f"{index}. {peer_id}")
+        choice = await asyncio.to_thread(input, "Select a person, [r]efresh, or [q]uit: ")
+        normalized = choice.strip().lower()
+        if normalized == "q":
+            return None
+        if normalized == "r" or not normalized:
+            continue
+        try:
+            selected = peers[int(normalized) - 1]
+        except (ValueError, IndexError):
+            print("Choose a listed number, r, or q.")
+            continue
+        return selected
+
+
+async def _receive_chat_messages(client: CyphraClient, peer_id: str) -> None:
+    while True:
+        try:
+            received = await client.receive_message()
+        except asyncio.CancelledError:
+            raise
+        except BrokerError as exc:
+            print(f"\nRelay connection ended: {exc}")
+            return
+        except CyphraError as exc:
+            print(f"\nCould not accept a message: {exc}")
+            continue
+        message = received.plaintext.decode("utf-8", errors="replace")
+        print(f"\n{peer_id[:12]}> {message}")
+
+
+def _prompt_database_passphrase(path: Path) -> str:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    is_existing = path.exists()
+    while True:
+        prompt = "Database passphrase: " if is_existing else "Create a database passphrase (12+ characters): "
+        passphrase = getpass.getpass(prompt)
+        if len(passphrase.encode("utf-8")) < 12:
+            print("Use at least 12 characters.")
+            continue
+        if is_existing:
+            return passphrase
+        confirmation = getpass.getpass("Confirm passphrase: ")
+        if passphrase == confirmation:
+            return passphrase
+        print("Passphrases did not match.")
+
+
+def _is_loopback_host(host: str | None) -> bool:
+    if host is None:
+        return False
+    if host.lower() == "localhost":
+        return True
+    try:
+        import ipaddress
+
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False

cyphra/client.py

@@ -0,0 +1,160 @@
+"""High-level client composition root.
+
+This is the only layer that composes the three independent boundaries:
+``CryptoEngine`` (client-only secrets), ``DatabaseManager`` (encrypted local
+state), and ``BrokerTransport`` (opaque network frames).
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+
+from cyphra.crypto.engine import CryptoEngine
+from cyphra.exceptions import (
+    EnvelopeError,
+    ReplayDetectedError,
+    SignatureVerificationError,
+    TrustRequiredError,
+)
+from cyphra.models import EncryptedEnvelope, PreKeyBundle
+from cyphra.network.client import BrokerTransport
+from cyphra.network.protocol import RelayPacket
+from cyphra.storage.database import DatabaseManager
+
+
+@dataclass(frozen=True, slots=True)
+class ReceivedMessage:
+    """A decrypted message returned to application code; never persisted."""
+
+    envelope: EncryptedEnvelope
+    plaintext: bytes
+
+
+class CyphraClient:
+    """Compose crypto, storage, and transport without leaking plaintext."""
+
+    def __init__(
+        self,
+        engine: CryptoEngine,
+        database: DatabaseManager,
+        transport: BrokerTransport,
+    ) -> None:
+        self.engine = engine
+        self.database = database
+        self.transport = transport
+        self._pending_packets: deque[RelayPacket] = deque()
+
+    @classmethod
+    def provision_identity(cls, engine: CryptoEngine, database: DatabaseManager) -> bytes:
+        """Generate and store a new local identity; return its public bundle."""
+
+        material = engine.generate_identity()
+        database.save_identity(material)
+        return material.bundle.to_bytes()
+
+    async def connect(self) -> None:
+        material = self.database.load_identity()
+        self.engine.validate_identity(material)
+        await self.transport.connect(material.identity_id, material.bundle.to_bytes())
+
+    async def discover_contact(self, identity_id: str) -> tuple[PreKeyBundle, str]:
+        """Fetch a public bundle and return it with a fingerprint for approval."""
+
+        raw = await self.transport.get_bundle(identity_id)
+        bundle = PreKeyBundle.from_bytes(raw)
+        self.engine.verify_bundle(bundle)
+        if bundle.identity_id != identity_id:
+            raise SignatureVerificationError("directory returned a different identity")
+        return bundle, self.engine.identity_fingerprint(bundle)
+
+    def approve_contact(self, bundle: PreKeyBundle, fingerprint: str) -> None:
+        """Persist an explicitly verified contact binding.
+
+        The fingerprint should have been compared out of band (for example by
+        scanning a QR code or reading a verified channel).  The relay is not a
+        trust anchor.
+        """
+
+        self.engine.verify_bundle(bundle)
+        expected = self.engine.identity_fingerprint(bundle)
+        if fingerprint != expected:
+            raise SignatureVerificationError("contact fingerprint does not match the bundle")
+        self.database.save_trusted_contact(bundle, fingerprint)
+
+    async def send_message(
+        self,
+        recipient_id: str,
+        plaintext: bytes,
+        *,
+        conversation_id: str,
+        recipient_bundle: PreKeyBundle | None = None,
+    ) -> EncryptedEnvelope:
+        """Encrypt locally, persist only ciphertext, and relay the opaque bytes."""
+
+        if recipient_bundle is None:
+            recipient_bundle = self.database.load_trusted_contact(recipient_id)
+        if recipient_bundle is None:
+            discovered, fingerprint = await self.discover_contact(recipient_id)
+            raise TrustRequiredError(
+                f"contact is not approved; verify fingerprint {fingerprint} and call approve_contact"
+            )
+        if recipient_bundle.identity_id != recipient_id:
+            raise SignatureVerificationError("recipient bundle identity mismatch")
+        self.engine.verify_bundle(recipient_bundle)
+        sender = self.database.load_identity()
+        envelope = self.engine.encrypt_message(
+            sender,
+            recipient_bundle,
+            plaintext,
+            conversation_id=conversation_id,
+        )
+        self.database.save_envelope(envelope, direction="outgoing", delivered=False)
+        await self.transport.send(
+            RelayPacket(
+                message_id=envelope.message_id,
+                sender_id=envelope.sender_id,
+                recipient_id=envelope.recipient_id,
+                payload=envelope.to_bytes(),
+            )
+        )
+        self.database.mark_delivered(envelope.message_id)
+        return envelope
+
+    async def receive_message(self) -> ReceivedMessage:
+        """Receive, authenticate, decrypt, and return one message in memory."""
+
+        packet = self._pending_packets.popleft() if self._pending_packets else await self.transport.receive()
+        try:
+            envelope = EncryptedEnvelope.from_bytes(packet.payload)
+        except EnvelopeError:
+            raise
+        if (
+            envelope.message_id != packet.message_id
+            or envelope.sender_id != packet.sender_id
+            or envelope.recipient_id != packet.recipient_id
+        ):
+            raise EnvelopeError("relay metadata does not match the encrypted envelope")
+        if self.database.has_envelope(envelope.message_id):
+            raise ReplayDetectedError("message identifier has already been accepted")
+
+        trusted_sender = self.database.load_trusted_contact(envelope.sender_id)
+        if trusted_sender is None:
+            self._pending_packets.appendleft(packet)
+            _bundle, fingerprint = await self.discover_contact(envelope.sender_id)
+            raise TrustRequiredError(
+                f"sender is not approved; verify fingerprint {fingerprint} and call approve_contact"
+            )
+
+        recipient = self.database.load_identity(envelope.recipient_key_id)
+        plaintext = self.engine.decrypt_message(
+            recipient,
+            envelope,
+            expected_sender=trusted_sender,
+        )
+        self.database.save_envelope(envelope, direction="incoming", delivered=True)
+        return ReceivedMessage(envelope=envelope, plaintext=plaintext)
+
+    async def close(self) -> None:
+        await self.transport.close()
+

cyphra/constants.py

@@ -0,0 +1,15 @@
+"""Protocol constants shared by the client and the relay."""
+
+from __future__ import annotations
+
+PROTOCOL_VERSION = 1
+DEFAULT_BROKER_URL = "https://post-q.vercel.app"
+HYBRID_SUITE = "CYPHRA-HYBRID-X25519-MLKEM-768-AES-256-GCM"
+MAX_MESSAGE_BYTES = 1_048_576
+MAX_RELAY_FRAME_BYTES = 2_000_000
+IDENTITY_ID_BYTES = 32
+KEY_ID_BYTES = 16
+NONCE_BYTES = 12
+KDF_SALT_BYTES = 32
+MESSAGE_KEY_BYTES = 32
+

cyphra/crypto/__init__.py

@@ -0,0 +1,5 @@
+"""Client-side cryptographic execution matrix."""
+
+from cyphra.crypto.engine import CryptoEngine
+
+__all__ = ["CryptoEngine"]

cyphra/crypto/backend.py

@@ -0,0 +1,98 @@
+"""NIST ML-KEM-768 backend adapters.
+
+The protocol deliberately has no classical-only fallback.  A deployment must
+provide a vetted ML-KEM-768 implementation or fail closed at startup.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Final
+
+from cyphra.exceptions import DependencyUnavailableError, InvalidKeyMaterial
+
+MLKEM768_PUBLIC_KEY_SIZE: Final = 1184
+MLKEM768_PRIVATE_KEY_SIZE: Final = 2400
+MLKEM768_CIPHERTEXT_SIZE: Final = 1088
+MLKEM768_SHARED_SECRET_SIZE: Final = 32
+
+
+class MLKEM768Backend(ABC):
+    """Small interface consumed by ``CryptoEngine`` only."""
+
+    algorithm = "ML-KEM-768"
+
+    @abstractmethod
+    def generate_keypair(self) -> tuple[bytes, bytes]:
+        """Return ``(public_key, private_key)`` in the NIST encoding."""
+
+    @abstractmethod
+    def encapsulate(self, public_key: bytes) -> tuple[bytes, bytes]:
+        """Return ``(ciphertext, shared_secret)``."""
+
+    @abstractmethod
+    def decapsulate(self, private_key: bytes, ciphertext: bytes) -> bytes:
+        """Return the shared secret or raise for malformed input."""
+
+
+class PqcryptoMLKEM768Backend(MLKEM768Backend):
+    """Adapter for the audited ``pqcrypto`` ML-KEM implementation."""
+
+    def __init__(self) -> None:
+        try:
+            from pqcrypto.kem import ml_kem_768
+        except ImportError as exc:  # pragma: no cover - depends on deployment
+            raise DependencyUnavailableError(
+                "pqcrypto with ML-KEM-768 support is required; refusing to start without it"
+            ) from exc
+        self._kem = ml_kem_768
+
+    def generate_keypair(self) -> tuple[bytes, bytes]:
+        try:
+            public_key, private_key = self._kem.keygen()
+        except Exception as exc:  # vendor exceptions vary by binding
+            raise InvalidKeyMaterial("ML-KEM-768 key generation failed") from exc
+        self._validate_public(public_key)
+        self._validate_private(private_key)
+        return bytes(public_key), bytes(private_key)
+
+    def encapsulate(self, public_key: bytes) -> tuple[bytes, bytes]:
+        self._validate_public(public_key)
+        try:
+            ciphertext, shared_secret = self._kem.encaps(public_key)
+        except Exception as exc:
+            raise InvalidKeyMaterial("ML-KEM-768 encapsulation failed") from exc
+        if len(ciphertext) != MLKEM768_CIPHERTEXT_SIZE:
+            raise InvalidKeyMaterial("ML-KEM-768 returned an invalid ciphertext")
+        if len(shared_secret) != MLKEM768_SHARED_SECRET_SIZE:
+            raise InvalidKeyMaterial("ML-KEM-768 returned an invalid shared secret")
+        return bytes(ciphertext), bytes(shared_secret)
+
+    def decapsulate(self, private_key: bytes, ciphertext: bytes) -> bytes:
+        self._validate_private(private_key)
+        if len(ciphertext) != MLKEM768_CIPHERTEXT_SIZE:
+            raise InvalidKeyMaterial("invalid ML-KEM-768 ciphertext length")
+        try:
+            shared_secret = self._kem.decaps(private_key, ciphertext)
+        except Exception as exc:
+            raise InvalidKeyMaterial("ML-KEM-768 decapsulation failed") from exc
+        if len(shared_secret) != MLKEM768_SHARED_SECRET_SIZE:
+            raise InvalidKeyMaterial("ML-KEM-768 returned an invalid shared secret")
+        return bytes(shared_secret)
+
+    @staticmethod
+    def _validate_public(public_key: bytes) -> None:
+        if not isinstance(public_key, bytes) or len(public_key) != MLKEM768_PUBLIC_KEY_SIZE:
+            raise InvalidKeyMaterial("ML-KEM-768 public key must be 1184 bytes")
+
+    @staticmethod
+    def _validate_private(private_key: bytes) -> None:
+        if not isinstance(private_key, bytes) or len(private_key) != MLKEM768_PRIVATE_KEY_SIZE:
+            raise InvalidKeyMaterial("ML-KEM-768 private key must be 2400 bytes")
+
+
+def default_mlkem_backend() -> MLKEM768Backend:
+    """Construct the mandatory ML-KEM-768 implementation."""
+
+    return PqcryptoMLKEM768Backend()
+