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

                  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

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.

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:

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

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.

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:

python3 -m twine upload dist/*

Never commit PyPI credentials. Increment the version in pyproject.toml for every release.

Testing

pytest -q
python3 -m py_compile api/index.py cyphra/**/*.py cyphra/*.py tests/*.py