Metadata-Version: 2.4
Name: uxsp
Version: 0.1.0
Summary: Universal Exchange Security Protocol — Hybrid Post-Quantum Secure Messaging
Author-email: SIVA RAJA S <sivaraja5401@gmail.com>
Project-URL: Repository, https://github.com/SIVA-RAJA/uxsp
Keywords: security,cryptography,post-quantum,pqc,kyber,dilithium,hybrid-encryption,secure-messaging
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: cryptography==47.0.0
Requires-Dist: liboqs-python==0.14.1
Requires-Dist: argon2-cffi==25.1.0
Provides-Extra: redis
Requires-Dist: redis==7.4.0; extra == "redis"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary==2.9.12; extra == "postgres"
Provides-Extra: dev
Requires-Dist: pytest==9.0.3; extra == "dev"
Requires-Dist: pytest-cov==7.1.0; extra == "dev"
Requires-Dist: mypy==1.20.2; extra == "dev"
Requires-Dist: ruff==0.15.12; extra == "dev"
Requires-Dist: fakeredis==2.35.1; extra == "dev"
Provides-Extra: docs
Requires-Dist: Sphinx==9.1.0; extra == "docs"
Requires-Dist: furo==2025.12.19; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints==3.10.2; extra == "docs"

# UXSP — Universal Exchange Security Protocol

[![Security: Hybrid PQC](https://img.shields.io/badge/Security-Hybrid%20PQC-blueviolet)](https://openquantumsafe.org/)
[![Python: 3.11+](https://img.shields.io/badge/Python-3.11+-blue)](https://www.python.org/)

UXSP is a high-security, domain-agnostic messaging protocol designed for the **Post-Quantum (PQ)** era. It ensures that your data remains private even if an attacker captures it today and attempts to decrypt it later with a powerful quantum computer (Store-Now-Decrypt-Later attack).

---

## 📋 Prerequisites (System Level)

UXSP relies on the **Open Quantum Safe (liboqs)** C library for its quantum-resistant primitives. You must install this on your system before the Python package can work.

| OS | Installation Command |
| :--- | :--- |
| **Ubuntu/Debian** | `sudo apt install liboqs` |
| **Fedora** | `sudo dnf install liboqs` |
| **macOS (Homebrew)** | `brew install liboqs` |
| **Windows** | Build from source via [liboqs GitHub](https://github.com/open-quantum-safe/liboqs) |

---

## 📦 Installation

UXSP is designed to be lightweight. You only install what you need.

```bash
# 1. Base Installation (includes Memory Storage)
pip install uxsp

# 2. Optional: Add Redis support for distributed replay protection
pip install "uxsp[redis]"

# 3. Optional: Add Postgres support for durable audit logging
pip install "uxsp[postgres]"
```

---

## 🚀 Crystal Clear Quick Start

This guide demonstrates a complete secure exchange between two peers (**Alice** and **Bob**).

### 1. Identity Setup (Private & Public Keys)
Every participant needs an `Identity`. This generates both classical (X25519/Ed25519) and PQ (ML-KEM/ML-DSA) keypairs.

```python
from uxsp.core.identity import Identity

# Create Alice's identity
# "NODE-A" is a 'Role' string—you can define any role that fits your project.
alice = Identity.create("Alice", "NODE-A")

# Securely save the identity to a file. 
# The private keys are encrypted with AES-256-GCM using your password.
alice.save("alice.uxsp", password="my_secret_password")

# Export the PublicCard. This is what you share with Bob.
# It contains ONLY public keys and is safe to send over the network.
alice_card = alice.public_card()
```

### 2. Establishing the Secure Session (The Handshake)
Alice and Bob must perform a **3-step handshake** to verify each other's identity and agree on a shared encryption key.

```python
from uxsp.core.handshake import Handshake

# --- STEP 1: Alice Initiates ---
# Alice uses her private Identity and Bob's PublicCard to start.
hs_init = Handshake.initiate(alice, bob_card)
hello_msg = hs_init.hello_message  # Send this dictionary to Bob

# --- STEP 2: Bob Responds ---
# Bob receives the 'hello_msg' and Alice's 'alice_card'.
# He verifies Alice's signature and establishes his side of the session.
hs_resp = Handshake.respond(bob, hello_msg, alice_card)
ack_msg = hs_resp.ack_message  # Send this back to Alice
bob_session = hs_resp.session   # Bob's session is now ACTIVE

# --- STEP 3: Alice Completes ---
# Alice receives the 'ack_msg' and verifies Bob's signature.
# If verification passes, her session becomes ACTIVE.
alice_session = hs_init.complete(ack_msg, bob_card)
```

### 3. Secure Communication
Once the session is active, you can send encrypted data. UXSP manages **Sequence Numbers** automatically to prevent attackers from reordering or replaying your messages.

```python
# --- Alice Sends ---
message = b"Secret data: 42"
payload = alice_session.encrypt(message) # Returns a dict with ciphertext

# --- Bob Receives ---
# Bob decrypts the payload. If the message was replayed or arrived 
# out of order, UXSP will raise a 'SessionReorderError'.
plaintext = bob_session.decrypt(payload)
print(plaintext.decode()) # Output: Secret data: 42
```

---

## 🛠️ Core Components

*   **`uxsp.core.identity`**: Identity management and encrypted local storage.
*   **`uxsp.core.handshake`**: The 3-step hybrid mutual authentication engine.
*   **`uxsp.core.session`**: Stateful encryption with sequence enforcement.
*   **`uxsp.storage`**: High-performance backends for Replay Protection.

## 🧪 Testing
Run the full suite to verify your system's `liboqs` compatibility:
```bash
pytest tests/
```
