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
```
