cyphra 0.1.0__tar.gz

cyphra-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: cyphra
+Version: 0.1.0
+Summary: Zero-knowledge hybrid E2EE messaging reference platform
+Maintainer: Anupam1707, asmitbaldi
+Project-URL: Homepage, https://github.com/Anupam1707/PostQ
+Project-URL: Repository, https://github.com/Anupam1707/PostQ
+Project-URL: Issues, https://github.com/Anupam1707/PostQ/issues
+Keywords: messaging,end-to-end-encryption,post-quantum,ml-kem,sqlcipher
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: argon2-cffi>=23.1.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: pqcrypto>=1.0.0
+Requires-Dist: sqlcipher3>=0.6.2
+Requires-Dist: websockets<17.0,>=14.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+
+# Cyphra
+
+Cyphra is a Python reference implementation of a zero-knowledge, end-to-end encrypted messaging platform. It supports two modes:
+
+1. A standalone terminal messaging client.
+2. An importable Python SDK for developer applications.
+
+Maintainers: `Anupam1707` and `asmitbaldi`.
+
+The mandatory hybrid construction is:
+
+`X25519 ephemeral DH || ML-KEM-768 encapsulation -> HKDF-SHA384 -> AES-256-GCM`
+
+Every message carries an Ed25519 signature over its canonical envelope.
+
+## Architecture
+
+```text
+                  untrusted network
+   ┌───────────────┐   opaque frames   ┌────────────────┐
+   │  CyphraClient │◄─────────────────►│ WebSocketBroker│
+   └──────┬────────┘                   └────────────────┘
+          │ composes
+   ┌──────▼────────┐       ciphertext-only local state
+   │  CryptoEngine │◄──────────────────────────────┐
+   └───────────────┘                               │
+                                      ┌────────────▼─────────┐
+                                      │   DatabaseManager    │
+                                      │      SQLCipher       │
+                                      └──────────────────────┘
+```
+
+- `CryptoEngine` owns identity generation, bundle verification, hybrid encryption, signatures, and decryption.
+- `DatabaseManager` owns SQLCipher persistence and stores private identity material, trusted contacts, and encrypted envelopes only.
+- `CyphraClient` composes cryptography, storage, and transport.
+- The fixed Vercel HTTP relay routes public bundles and opaque ciphertext without receiving plaintext or private keys.
+
+## Install
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python3 -m pip install -e '.[dev]'
+```
+
+## Standalone Client
+
+The client uses the fixed deployed relay internally. Users do not select a broker URL.
+
+```bash
+cyphra chat --name Alice
+cyphra chat --name Bob
+```
+
+The terminal UI shows connected people, supports `r` to refresh and `q` to quit, and asks the user to approve the peer fingerprint before chatting. Type `/quit` to leave.
+
+Each identity uses its own encrypted database under `~/.cyphra/`; use `--db` for a custom path.
+
+## SDK Mode
+
+Developer applications can import Cyphra components directly:
+
+```python
+from cyphra import CyphraClient, CryptoEngine, DatabaseManager
+from cyphra.network.http_client import HttpBrokerClient
+
+engine = CryptoEngine()
+database = DatabaseManager.from_passphrase("alice.db", "a long local passphrase")
+CyphraClient.provision_identity(engine, database)
+transport = HttpBrokerClient("https://post-q.vercel.app")
+client = CyphraClient(engine, database, transport)
+```
+
+## Fixed Vercel Relay
+
+The deployed relay URL is `https://post-q.vercel.app`.
+
+The Vercel handler uses transient process memory for public bundles, presence, and temporary opaque packet forwarding. No external database is configured. Persistent identities, contacts, and encrypted message history remain in each client database.
+
+Because serverless memory is not durable or shared across every instance, this relay is suitable for controlled demonstrations and testing, not reliable offline delivery.
+
+Deploy through the Vercel GitHub integration by importing `Anupam1707/PostQ`, selecting **Other** as the framework, and deploying the `main` branch.
+
+## Local Relay Development
+
+```bash
+cyphra-server --insecure-dev --host 127.0.0.1 --port 8765
+```
+
+The local WebSocket relay remains available for development and tests, but the normal standalone client uses the fixed Vercel HTTPS relay.
+
+## Security Notes
+
+- ML-KEM-768 is mandatory; there is no classical-only downgrade path.
+- Each message gets fresh X25519 ephemeral material, ML-KEM encapsulation, HKDF salt, and AES-GCM nonce.
+- The relay sees identity IDs, public bundles, timing, sizes, and opaque ciphertext.
+- Plaintext, private keys, passphrases, and derived message keys remain client-side.
+- Offline delivery is intentionally not guaranteed by the transient relay.
+- This is a security-focused reference implementation, not a substitute for independent cryptographic review.
+
+## Build and Publish
+
+The package provides the `cyphra` and `cyphra-server` console commands.
+
+```bash
+rm -rf dist build *.egg-info
+python3 -m build
+python3 -m twine check dist/*
+python3 -m pip install --force-reinstall dist/cyphra-*.whl
+cyphra --help
+```
+
+Publish after reviewing the artifacts:
+
+```bash
+python3 -m twine upload dist/*
+```
+
+Never commit PyPI credentials. Increment the version in `pyproject.toml` for every release.
+
+## Testing
+
+```bash
+pytest -q
+python3 -m py_compile api/index.py cyphra/**/*.py cyphra/*.py tests/*.py
+```

cyphra-0.1.0/README.md

@@ -0,0 +1,126 @@
+# Cyphra
+
+Cyphra is a Python reference implementation of a zero-knowledge, end-to-end encrypted messaging platform. It supports two modes:
+
+1. A standalone terminal messaging client.
+2. An importable Python SDK for developer applications.
+
+Maintainers: `Anupam1707` and `asmitbaldi`.
+
+The mandatory hybrid construction is:
+
+`X25519 ephemeral DH || ML-KEM-768 encapsulation -> HKDF-SHA384 -> AES-256-GCM`
+
+Every message carries an Ed25519 signature over its canonical envelope.
+
+## Architecture
+
+```text
+                  untrusted network
+   ┌───────────────┐   opaque frames   ┌────────────────┐
+   │  CyphraClient │◄─────────────────►│ WebSocketBroker│
+   └──────┬────────┘                   └────────────────┘
+          │ composes
+   ┌──────▼────────┐       ciphertext-only local state
+   │  CryptoEngine │◄──────────────────────────────┐
+   └───────────────┘                               │
+                                      ┌────────────▼─────────┐
+                                      │   DatabaseManager    │
+                                      │      SQLCipher       │
+                                      └──────────────────────┘
+```
+
+- `CryptoEngine` owns identity generation, bundle verification, hybrid encryption, signatures, and decryption.
+- `DatabaseManager` owns SQLCipher persistence and stores private identity material, trusted contacts, and encrypted envelopes only.
+- `CyphraClient` composes cryptography, storage, and transport.
+- The fixed Vercel HTTP relay routes public bundles and opaque ciphertext without receiving plaintext or private keys.
+
+## Install
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python3 -m pip install -e '.[dev]'
+```
+
+## Standalone Client
+
+The client uses the fixed deployed relay internally. Users do not select a broker URL.
+
+```bash
+cyphra chat --name Alice
+cyphra chat --name Bob
+```
+
+The terminal UI shows connected people, supports `r` to refresh and `q` to quit, and asks the user to approve the peer fingerprint before chatting. Type `/quit` to leave.
+
+Each identity uses its own encrypted database under `~/.cyphra/`; use `--db` for a custom path.
+
+## SDK Mode
+
+Developer applications can import Cyphra components directly:
+
+```python
+from cyphra import CyphraClient, CryptoEngine, DatabaseManager
+from cyphra.network.http_client import HttpBrokerClient
+
+engine = CryptoEngine()
+database = DatabaseManager.from_passphrase("alice.db", "a long local passphrase")
+CyphraClient.provision_identity(engine, database)
+transport = HttpBrokerClient("https://post-q.vercel.app")
+client = CyphraClient(engine, database, transport)
+```
+
+## Fixed Vercel Relay
+
+The deployed relay URL is `https://post-q.vercel.app`.
+
+The Vercel handler uses transient process memory for public bundles, presence, and temporary opaque packet forwarding. No external database is configured. Persistent identities, contacts, and encrypted message history remain in each client database.
+
+Because serverless memory is not durable or shared across every instance, this relay is suitable for controlled demonstrations and testing, not reliable offline delivery.
+
+Deploy through the Vercel GitHub integration by importing `Anupam1707/PostQ`, selecting **Other** as the framework, and deploying the `main` branch.
+
+## Local Relay Development
+
+```bash
+cyphra-server --insecure-dev --host 127.0.0.1 --port 8765
+```
+
+The local WebSocket relay remains available for development and tests, but the normal standalone client uses the fixed Vercel HTTPS relay.
+
+## Security Notes
+
+- ML-KEM-768 is mandatory; there is no classical-only downgrade path.
+- Each message gets fresh X25519 ephemeral material, ML-KEM encapsulation, HKDF salt, and AES-GCM nonce.
+- The relay sees identity IDs, public bundles, timing, sizes, and opaque ciphertext.
+- Plaintext, private keys, passphrases, and derived message keys remain client-side.
+- Offline delivery is intentionally not guaranteed by the transient relay.
+- This is a security-focused reference implementation, not a substitute for independent cryptographic review.
+
+## Build and Publish
+
+The package provides the `cyphra` and `cyphra-server` console commands.
+
+```bash
+rm -rf dist build *.egg-info
+python3 -m build
+python3 -m twine check dist/*
+python3 -m pip install --force-reinstall dist/cyphra-*.whl
+cyphra --help
+```
+
+Publish after reviewing the artifacts:
+
+```bash
+python3 -m twine upload dist/*
+```
+
+Never commit PyPI credentials. Increment the version in `pyproject.toml` for every release.
+
+## Testing
+
+```bash
+pytest -q
+python3 -m py_compile api/index.py cyphra/**/*.py cyphra/*.py tests/*.py
+```

cyphra-0.1.0/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-0.1.0/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-0.1.0/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()
+