Cyphra

Cyphra is a Python package for building client-side encrypted messaging applications. It provides both a ready-to-run terminal client and reusable SDK components for developer applications.

Why Cyphra

Cyphra is designed around an explicit trust boundary:

• Identity keys are generated on the client.
• Private keys and plaintext remain on the client.
• Trusted contacts are approved using a human-readable fingerprint.
• Messages are encrypted and signed before they leave the client.
• The relay routes public data and opaque ciphertext without decrypting messages.
• Persistent identity, contact, and encrypted-message data is stored in a local SQLCipher database.

The package is a security-focused reference implementation. It should receive an independent cryptographic and operational review before production use.

Two Usage Modes

Standalone terminal application

Install the package and launch the client with a local display name:

python3 -m pip install cyphra
cyphra chat --name Alice

The terminal client creates or opens a local encrypted database, registers its public identity, displays connected people, supports fingerprint approval, and provides encrypted messaging. A second user can run cyphra chat --name Bob.

The fixed relay URL is configured by the application. The user does not need to select a broker. Each local profile has its own database under ~/.cyphra/ unless --db is supplied.

Developer SDK

Applications can compose Cyphra directly instead of using the terminal UI:

from cyphra import CyphraClient, CryptoEngine, DatabaseManager
from cyphra.network.http_client import HttpBrokerClient

engine = CryptoEngine()
database = DatabaseManager.from_passphrase(
    "alice.db",
    "a local passphrase with at least 12 characters",
)
CyphraClient.provision_identity(engine, database)
transport = HttpBrokerClient("https://post-q.vercel.app")
client = CyphraClient(engine, database, transport)

The SDK exposes the same security workflow as the standalone application: connect, discover a contact, compare fingerprints, approve the contact, send encrypted messages, and receive authenticated messages.

Cryptographic Suite

Each message uses a mandatory hybrid construction:

X25519 ephemeral DH
    ||
ML-KEM-768 encapsulation
    -> HKDF-SHA384
    -> AES-256-GCM encryption
    -> Ed25519 envelope signature

There is no classical-only downgrade path. Each message receives fresh ephemeral key material, a fresh KDF salt, and a fresh AES-GCM nonce. Recipients verify routing metadata, contact trust, signatures, timestamps, and replay identifiers before displaying plaintext.

Local Storage

Cyphra uses SQLCipher for local persistence and Argon2id to derive the database key from the user's passphrase. The local database stores private identity material, approved contact bundles, fingerprints, and encrypted envelopes. It does not provide a plaintext storage API.

The relay can observe identity IDs, public bundles, message IDs, timing, packet sizes, and ciphertext. It must not receive private keys, passphrases, derived message keys, or plaintext.

Relay Behavior

The default relay is the deployed HTTPS application at https://post-q.vercel.app. It supports registration, public-bundle lookup, active-peer lookup, opaque packet forwarding, and polling.

The relay uses transient process memory and no external database. It is suitable for demonstrations and controlled testing, but it does not guarantee offline delivery across serverless instances. Applications requiring durable delivery should add a separately audited opaque store-and-forward service.

Public API

The primary public objects are:

• CyphraClient: application workflow coordinator.
• CryptoEngine: identity, encryption, signature, and decryption service.
• DatabaseManager: local SQLCipher persistence service.
• BrokerTransport: transport interface for relay implementations.
• HttpBrokerClient: fixed deployed HTTPS transport.
• EncryptedEnvelope: authenticated encrypted message value object.
• PreKeyBundle: signed public identity bundle value object.

Security and Scope

Cyphra does not provide anonymity, traffic-analysis resistance, group messaging, multi-device synchronization, account recovery, hardware-backed keys, or production abuse controls. It is intended to demonstrate endpoint encryption, explicit trust, local encrypted storage, and object-oriented separation of responsibilities.

Maintainers

• Anupam1707
• asmitbaldi

Project

Repository: https://github.com/Anupam1707/PostQ