Metadata-Version: 2.4
Name: quantumshield-proxy
Version: 1.0.2
Summary: Zero-code-change Post-Quantum Cryptography (ML-KEM-768 / Kyber) Reverse Proxy
Author-email: Hemanth <dev@quantumshield.io>
Project-URL: Homepage, https://github.com/hemanth/Ccp_QuantumShield
Project-URL: Bug Tracker, https://github.com/hemanth/Ccp_QuantumShield/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: flask>=3.0.0
Requires-Dist: flask-cors>=4.0.0
Requires-Dist: liboqs-python>=0.10.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: requests>=2.31.0

# ⚡ QuantumShield PyPI Reverse Proxy (`quantumshield-proxy`)

> **Zero-Code-Change Post-Quantum Cryptography (PQC) Security Gateway**  
> Implementing **NIST FIPS 203 (ML-KEM-768 / CRYSTALS-Kyber)** key encapsulation mechanism via Open Quantum Safe (`liboqs`).

[![PyPI version](https://img.shields.io/pypi/v/quantumshield-proxy.svg)](https://pypi.org/project/quantumshield-proxy/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

---

## 🌟 Overview

`quantumshield-proxy` is a high-performance Python reverse proxy that upgrades legacy HTTP web applications and payment APIs to **NIST FIPS 203 (ML-KEM-768)** post-quantum cryptography **without requiring a single line of backend code modification**.

It acts as an inline quantum-safe gateway between client traffic and your target web application.

---

## ⚡ Installation

Install via `pip`:

```bash
pip install quantumshield-proxy
```

---

## 🚀 Usage Guide

### 1. Interactive Setup Wizard (Default)

Launch the wizard without flags for step-by-step terminal prompts:

```bash
quantumshield-proxy
```

Prompt walkthrough:
```text
🌐 QuantumShield PQC Reverse Proxy — Setup Wizard
─────────────────────────────────────────────────
Enter target upstream app URL [default: http://localhost:3001]: 
Enter proxy listening port [default: 8443]: 
Select initial protection mode ([1] RSA_ONLY / [2] KYBER_PQC) [default: 2]: 
```

### 2. Command Line Execution (Flags)

Run directly with explicit port, target upstream, and protection mode:

```bash
quantumshield-proxy --upstream http://localhost:3001 --port 8443 --mode KYBER_PQC
```

---

## ⚙️ CLI Options

| Flag | Short | Default | Description |
|---|---|---|---|
| `--port` | `-p` | `8443` | Listening port for the QuantumShield Reverse Proxy |
| `--upstream` | `-u` | `http://localhost:3001` | Upstream target application URL to forward traffic to |
| `--mode` | `-m` | `KYBER_PQC` | Protection mode (`KYBER_PQC` or `RSA_ONLY`) |
| `--help` | `-h` | - | Display help menu and CLI parameters |

---

## 📡 REST API Endpoints

The proxy exposes a built-in control plane API on its listening port (`8443` by default):

| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/api/proxy/status` | Current proxy state, active algorithm, and uptime |
| `POST` | `/api/proxy/activate` | Dynamically toggle protection mode (`KYBER_PQC` ↔ `RSA_ONLY`) |
| `GET` | `/api/proxy/pubkey` | Fetch ML-KEM-768 Public Key (1184-byte hex) |
| `POST` | `/api/proxy/pay/kyber` | Decapsulate ML-KEM-768 ciphertext, decrypt payload & forward to upstream |
| `POST` | `/proxy/pay` | Legacy RSA payment endpoint (intercepted & logged in vault) |
| `GET` | `/api/proxy/vault` | Intercepted transaction vault records |
| `POST` | `/api/proxy/vault/clear` | Reset harvest vault |

---

## 🔒 Cryptographic Specifications

- **Standard**: NIST FIPS 203 (ML-KEM-768)
- **Library**: Open Quantum Safe (`liboqs` C-bindings)
- **Security Level**: Category 3 (Equivalent to AES-192 against Quantum Attackers)
- **Public Key Size**: 1,184 Bytes
- **Ciphertext Size**: 1,088 Bytes
- **Secret Key Size**: 2,400 Bytes

---
