Metadata-Version: 2.4
Name: broadencrypt
Version: 1.0.0
Summary: A production-quality local Post-Quantum Cryptography SDK for developers
Author-email: BroadEncrypt Contributors <omkoli3114@gmail.com>
License: MIT License
        
        Copyright (c) 2026 PQC Secure Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/omkoli3114/BroadEncrypt
Project-URL: Repository, https://github.com/omkoli3114/BroadEncrypt
Project-URL: Issues, https://github.com/omkoli3114/BroadEncrypt/issues
Project-URL: Documentation, https://github.com/omkoli3114/BroadEncrypt/tree/main/docs
Project-URL: Changelog, https://github.com/omkoli3114/BroadEncrypt/blob/main/CHANGELOG.md
Keywords: post-quantum,cryptography,ML-KEM,AES-GCM,encryption,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <4,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: keyring>=24.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Dynamic: license-file

<div align="center">
 
 <h1>🔐 BroadEncrypt</h1>
 
 <p><strong>Post-quantum encryption for the modern developer.</strong><br>
 Local. Open-source. Quantum-safe. No servers. No API keys. No compromise.</p>
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://www.python.org/)
 [![Tests](https://img.shields.io/badge/tests-131%20passed-brightgreen.svg)]()
 [![Algorithm](https://img.shields.io/badge/KEM-ML--KEM--768%20%28FIPS%20203%29-blueviolet.svg)]()
 [![Symmetric](https://img.shields.io/badge/Symmetric-AES--256--GCM-blueviolet.svg)]()
 [![Status](https://img.shields.io/badge/status-Community%20Edition-orange.svg)]()
 
 <br/>
 
 <img src="docs/demo.svg" alt="BroadEncrypt CLI demo — genkey, encrypt, decrypt" width="680"/>
 
 </div>
 
 ---
 
 ## What is BroadEncrypt?
 
 BroadEncrypt is a **local, open-source Post-Quantum Cryptography SDK** for developers who want to protect their data against both classical and quantum computer attacks — today, not someday.
 
 > **Quantum computers will break RSA, ECDSA, and Diffie-Hellman.**  
 > NIST finalized post-quantum standards in 2024.  
 > BroadEncrypt is the simplest way to adopt them.
 
 **Everything runs on your machine.** No cloud. No API. No data leaves your system.
 
 ---
 
 ## Why BroadEncrypt?
 
 | Problem | BroadEncrypt Solution |
 |---|---|
 | RSA/ECC will be broken by quantum computers | Uses **ML-KEM-768** (NIST FIPS 203) |
 | Most crypto SDKs require cloud APIs | **100% local** — runs entirely on your machine |
 | Encrypted file formats are fragile | Self-contained **`.pqc` format** bundles everything needed to decrypt |
 | Large files cause out-of-memory errors | **Automatic chunked streaming** for files > 10 MB (RAM limit ≤ 10 MB) |
 | Crypto libraries are hard to use | **Simple Python and JS APIs** — generate, encrypt, decrypt |
 | No CLI for quick use | Full **`broadencrypt` CLI** — one command to encrypt any file |
 
 ---
 
 ## Quick Start
 
 > **Prerequisite:** `liboqs` must be available. Install from [Open Quantum Safe](https://github.com/open-quantum-safe/liboqs-python) before installing BroadEncrypt:
 > ```bash
 > pip install git+https://github.com/open-quantum-safe/liboqs-python.git
 > ```
 
 ### Option 1: Install direct from GitHub (Recommended for now)
 
 No need to clone, just install directly from the source:
 
 ```bash
 pip install git+https://github.com/omkoli3114/BroadEncrypt.git
 ```
 
 ### Option 2: Clone & Install locally (Developer Mode)
 
 ```bash
 git clone https://github.com/omkoli3114/BroadEncrypt.git
 cd BroadEncrypt
 pip install -e .
 ```
 
 ### Option 3: PyPI (Coming soon)
 
 Once published to PyPI, you will be able to install it globally:
 
 ```bash
 pip install broadencrypt
 ```
 
 ### Running the Local Security Runtime
 
 BroadEncrypt runs over a local background daemon (`broadencryptd`). You must start the daemon before calling the SDK methods:
 
 ```bash
 broadencrypt start
 ```
 
 You can check status or stop the daemon at any time:
 ```bash
 broadencrypt status
 broadencrypt stop
 ```
 
 > **Windows note:** The daemon uses TCP loopback (127.0.0.1:27937) on Windows instead of a UNIX socket.
 > If you see a Windows Firewall prompt when first starting the daemon, allow access for `python.exe` on **private networks only**.
 
 ### Python API
 
 ```python
 from broadencrypt import Client
 
 # Automatically handles single-block (files ≤ 10MB) or streaming (files > 10MB)
 client = Client()
 
 # 1. Generate a quantum-safe keypair (one-time)
 client.generate_keys(output_dir="./keys", name="alice")
 # → keys/alice_public.key
 # → keys/alice_private.key
 
 # 2. Encrypt any file (share the .pqc, keep the private key safe)
 client.encrypt_file("contract.pdf", "contract.pqc", "keys/alice_public.key")
 
 # 3. Decrypt anywhere (only the private key is needed; auto-detects version & streaming format)
 client.decrypt_file("contract.pqc", "contract_recovered.pdf", "keys/alice_private.key")
 
 # 4. Rotate recipient key (re-encapsulates DEK envelope, doesn't re-encrypt payload!)
 client.rotate_key("contract.pqc", "contract_bob.pqc", "keys/alice_private.key", "keys/bob_public.key")
 ```
 
 ### JavaScript API (Node.js & TypeScript)
 
 ```javascript
 import { Client } from 'broadencrypt';
 
 const client = new Client();
 
 // 1. Generate a quantum-safe keypair (one-time)
 await client.generateKeys({ outputDir: './keys', name: 'alice' });
 // → keys/alice_public.key
 // → keys/alice_private.key
 
 // 2. Encrypt any file (auto-detects and uses chunked streaming for files > 10MB)
 await client.encryptFile('contract.pdf', 'contract.pqc', 'keys/alice_public.key');
 
 // 3. Decrypt anywhere
 await client.decryptFile('contract.pqc', 'contract_recovered.pdf', 'keys/alice_private.key');
 
 // 4. Rotate recipient key
 await client.rotateKey('contract.pqc', 'contract_bob.pqc', 'keys/alice_private.key', 'keys/bob_public.key');
 ```
 
 ### CLI
 
 ```bash
 # Generate a keypair
 broadencrypt genkey --output-dir ./keys --name alice
 
 # Encrypt any file
 broadencrypt encrypt contract.pdf contract.pqc keys/alice_public.key
 
 # Decrypt
 broadencrypt decrypt contract.pqc contract_recovered.pdf keys/alice_private.key
 
 # Rotate recipient key
 broadencrypt rotate contract.pqc contract_bob.pqc keys/alice_private.key keys/bob_public.key
 ```
 
 ---
 
 ## How It Works
 
 ### Single-Block Mode (Version 1, ≤ 10 MB)
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                       ENCRYPTION                            │
 │                                                             │
 │  Public Key ──→ ML-KEM-768 Encapsulate ──→ Shared Secret   │
 │                         │                        │          │
 │                    KEM Ciphertext         AES-256-GCM       │
 │                         │                   Encrypt         │
 │                         │                        │          │
 │                         └──────────┬─────────────┘          │
 │                                    ↓                        │
 │                            ┌──────────────┐                 │
 │                            │  .pqc file   │                 │
 │                            │  (one file,  │                 │
 │                            │  self-       │                 │
 │                            │  contained)  │                 │
 │                            └──────────────┘                 │
 └─────────────────────────────────────────────────────────────┘
 ```
 
 ### Chunked-Streaming Mode (Version 2, > 10 MB)
 
 For large files, BroadEncrypt automatically switches to Version 2. The file is encrypted and processed in 1 MB chunks:
 - **Unique Nonces**: Nonce per chunk `i` is derived as $\text{Base Nonce}[0..7] \mathbin{\Vert} \text{chunk\_index}$.
 - **Cryptographic Binding (AAD)**: Associated Data for chunk `i` is bound as $\text{chunk\_index} \mathbin{\Vert} \text{is\_last}$ to guard against chunk reordering, swapping, or truncation.
 
 ### Key Rotation & Envelope Mode (Version 3)
 
 Version 3 is the default format for new encryptions. Instead of encrypting the payload directly with the KEM shared secret, it uses an envelope encryption model:
 1. A fresh 32-byte **Data Encryption Key (DEK)** is generated.
 2. The payload is encrypted with the DEK using AES-256-GCM.
 3. A **Key Encryption Key (KEK)** is derived from the ML-KEM-768 shared secret using HKDF-SHA256.
 4. The DEK is encrypted with the KEK and stored in the header.
 
 **Key Rotation**: To transfer the file to a new recipient (or rotate keys), the old private key is used to decrypt the DEK envelope, and a new public key is used to re-encrypt only the DEK. The underlying payload ciphertext is copied byte-for-byte without decryption or re-encryption, making key rotation extremely fast.
 
 ----
 
 ## The `.pqc` File Format
 
 BroadEncrypt uses a self-describing binary format that bundles the encapsulated keys alongside the payload.
 
 ### Version 1: Single-Block Layout
 
 ```
 Offset  Size       Field
 ──────  ─────────  ──────────────────────────────────────────
 0       4 bytes    Magic: PQC\x01
 4       1 byte     Format version (1)
 5       16 bytes   Algorithm name (e.g. "ML-KEM-768")
 21      4 bytes    KEM ciphertext length (uint32, big-endian)
 25      1088 B     ML-KEM-768 ciphertext
 1113    12 bytes   AES-GCM nonce
 1125    variable   AES-GCM ciphertext + 16-byte auth tag
 ```
 
 ### Version 2: Chunked-Streaming Layout
 
 ```
 Offset  Size       Field
 ──────  ─────────  ──────────────────────────────────────────
 0       4 bytes    Magic: PQC\x01
 4       1 byte     Format version (2)
 5       16 bytes   Algorithm name (e.g. "ML-KEM-768")
 21      4 bytes    KEM ciphertext length (uint32, big-endian)
 25      4 bytes    Chunk Size (uint32, big-endian, e.g. 1,048,576 B)
 29      1088 B     ML-KEM-768 ciphertext
 1117    12 bytes   AES-GCM Base Nonce (first 8 bytes are used as chunk salt)
 1129    variable   Sequenced payload chunks:
                     - 4 bytes: Chunk Payload Length (uint32, big-endian)
                     - variable: AES-GCM ciphertext + 16-byte auth tag
 ```
 
 ### Version 3: HKDF + Encrypted DEK Envelope Layout
 
 ```
 Offset  Size       Field
 ──────  ─────────  ──────────────────────────────────────────
 0       4 bytes    Magic: PQC\x01
 4       1 byte     Format version (3)
 5       16 bytes   Algorithm name (e.g. "ML-KEM-768")
 21      4 bytes    KEM ciphertext length (uint32, big-endian)
 25      4 bytes    Chunk Size (uint32, big-endian, 0 = single-block, >0 = streaming)
 29      1088 B     ML-KEM-768 ciphertext
 1117    12 bytes   AES-GCM Nonce / Base Nonce
 1129    48 bytes   Encrypted DEK envelope (32-byte encrypted DEK + 16-byte tag)
 1177    variable   Payload (single-block or sequenced payload chunks)
 ```
 
 ----
 
 ## Error Handling
 
 ```python
 from broadencrypt import (
     Client,
     PQCDecryptionError,   # Wrong key or tampered file/chunk
     PQCFormatError,       # Invalid .pqc file or corrupted header
     PQCKeyError,          # Key file missing or corrupt
     PQCError,             # Base class — catches everything
 )
 
 client = Client()
 try:
     client.decrypt_file("data.pqc", "data.txt", "private.key")
 except PQCDecryptionError:
     print("Wrong key or the file was tampered with.")
 except PQCFormatError:
     print("Not a valid .pqc file.")
 except PQCKeyError as e:
     print(f"Key problem: {e}")
 ```
 
 ---
 
 ## Algorithms
 
 | Layer | Algorithm | Standard | Key Size |
 |---|---|---|---|
 | Key Encapsulation | **ML-KEM-768** | NIST FIPS 203 | Public: 1184 B / Private: 2400 B |
 | Symmetric Encryption | **AES-256-GCM** | NIST SP 800-38D | 32 B (shared secret) |
 
 Both are **NIST-standardized**. No custom cryptography. No experimental algorithms.

---

## Platform Compatibility

| Platform | Status | IPC Transport | Notes |
|---|---|---|---|
| **Linux** | ✅ Fully supported | UNIX domain socket | Recommended for production |
| **macOS** | ✅ Fully supported | UNIX domain socket | |
| **Windows 10/11** | ✅ Supported | TCP loopback (127.0.0.1:27937) | See [Windows notes](#windows-notes) |

### Windows Notes

- The daemon spawns as a hidden background process (`CREATE_NO_WINDOW`) and writes logs to `~/.broadencrypt/daemon.log`.
- `socket.AF_UNIX` is not available on Windows; BroadEncrypt automatically uses TCP loopback instead.
- The daemon process uses `CREATE_BREAKAWAY_FROM_JOB` to detach from the terminal's Windows Job Object, ensuring it survives after the launching shell exits.
- If you encounter a firewall prompt, allow `python.exe` on **private networks only** — all traffic is loopback only and never leaves your machine.
 
 ---
 
 ## Project Structure
 
 ```
 broadencrypt/
 ├── broadencrypt/             # Python SDK
 │   ├── client.py           # Public API: Client class (with streaming support)
 │   ├── exceptions.py       # Typed exception hierarchy
 │   ├── crypto/
 │   │   ├── kem.py          # ML-KEM-768 operations
 │   │   └── symmetric.py    # AES-256-GCM operations
 │   ├── formats/
 │   │   └── pqc_file.py     # .pqc binary formats (v1 & v2)
 │   ├── keys/
 │   │   └── manager.py      # Key file I/O
 │   └── cli/
 │       └── main.py         # broadencrypt CLI (Typer)
 ├── tests/                  # Python tests, 100% passing
 ├── examples/               # Runnable demos
 ├── docs/                   # API reference, CLI, file format spec
 └── js-sdk/                 # JavaScript SDK (ESM/TypeScript, with streaming support)
 ```
 
 ---
 
 ## Running Tests
 
 ### Python SDK Tests
 
 ```bash
 pip install -e ".[dev]"
 pytest
 # 76 passed ✓
 ```
 
 ### JavaScript SDK Tests
 
 ```bash
 cd js-sdk
 npm install
 npm run build
 npm test
 # 6 test suites passed (42 tests total) ✓
 ```
 
 ---
 
 ## CLI Reference
 
 ```bash
 broadencrypt --help              # All commands
 broadencrypt genkey --help       # Keypair generation options
 broadencrypt encrypt --help      # Encryption options
 broadencrypt decrypt --help      # Decryption options
 broadencrypt rotate --help       # Key rotation options
 broadencrypt --version           # Show version
 ```
 
 Full reference: [`docs/cli.md`](docs/cli.md)
 
 ---
 
 ## Roadmap
 
 - [x] **v1.x** — Python/JS SDK & CLI (ML-KEM-768 + AES-256-GCM + file streaming + rotation)
 - [x] **v2.x** — Local Security Runtime (Background daemon `broadencryptd` + socket IPC channels)
 - [x] **v3.x** — Desktop Application (Tauri Dashboard & Drag-and-Drop)
 - [x] **v4.x** — Enterprise Management Server (Control Plane & Policy Engine)
 - [x] **v5.x** — Advanced Security (OS Keychain Key Sealing, Auto-rotation, and ML-DSA CA PKI)
 
 ---
 
 ## Changelog
 
 ### Latest — Windows IPC Daemon Fixes
 
 Three Windows-specific bugs that caused `broadencryptd` to crash immediately on startup were identified and fixed:
 
 | Bug | Root Cause | Fix |
 |---|---|---|
 | `AttributeError: module 'socket' has no attribute 'AF_UNIX'` | `PQCServer.stop()` accessed `socket.AF_UNIX` unconditionally — this attribute does not exist on Windows | Guarded with `hasattr(socket, "AF_UNIX")` |
 | Daemon exits silently after parent shell closes | `subprocess.Popen` inherits the terminal's Windows Job Object (`JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`), killing all child processes when the shell exits | Added `CREATE_BREAKAWAY_FROM_JOB` (0x01000000) to spawn flags |
 | Daemon crashes with DEVNULL stderr | The `liboqs` C library writes to stderr at startup; a null C-level file descriptor caused a silent native crash | Redirected stdout/stderr to the daemon log file instead of `subprocess.DEVNULL` |
 
 Additionally, the `run_daemon()` keepalive loop was made more robust by replacing `threads[0].join()` (which could raise `IndexError`) with a `threading.Event` wait loop.
 
 ---
 
 ## Security
 
 BroadEncrypt is designed with security-first controls following post-quantum and classical hygiene standards:
 
 - **No custom cryptography.** All primitives come from [liboqs](https://github.com/open-quantum-safe/liboqs) (Open Quantum Safe), [cryptography.io](https://cryptography.io/) (PyCA), and [@noble/post-quantum](https://github.com/paulmillr/noble-post-quantum).
 - **No network calls or telemetry.** The SDK is 100% local and never transmits data.
 - **Owner-Only Permissions (SEC-01)**: Key files are written with `0o600` permissions (read/write by owner only) on POSIX.
 - **Memory Zeroing (SEC-02)**: All cryptographic key materials (`private_key`, `shared_secret`, `dek`/`sym_key`, `kek`) are explicitly zeroed out in-place in memory immediately after use (using `ctypes` memory overwrites in Python and `.fill(0)` on `Uint8Array` in JavaScript).
 - **Atomic Swap Writes (SEC-04)**: During decryption/rotation, output files are written to a temporary location (with secure `0o600` permissions) first and swapped atomically upon success, preventing partial plaintexts on failure.
 - **OOM Prevention (SEC-05)**: Configurable file size checks (default limit of `512 MB`) reject excessively large inputs before memory allocation to prevent heap exhaustion/denial-of-service.
 - **Tamper Detection**: AES-256-GCM authenticated encryption guarantees payload integrity and detects chunk re-ordering or tampering.
 - **Keychain Sealing (SEC-08)**: Private key files can optionally be sealed on disk via OS-native Keychains (Windows DPAPI, macOS Keychain Access, Linux Secret Service), encrypting them with a random 256-bit AES-GCM master key that never touches the filesystem in plaintext.
 
 **Found a vulnerability?** Please open a private GitHub Security Advisory — do not file a public issue.
 
 ---
 
 ## Contributing
 
 Contributions are welcome!
 
 1. Fork the repository
 2. Create a feature branch: `git checkout -b feature/your-feature`
 3. Install dev dependencies: `pip install -e ".[dev]"`
 4. Run tests: `pytest`
 5. Open a Pull Request
 
 Areas where help is especially welcome:
 - **Go / Rust SDK** bindings
 - **Benchmarks** and performance analysis
 - **Documentation** improvements
 
 ---
 
 ## License
 
 MIT © BroadEncrypt Contributors
 
 ---
 
 <div align="center">
 
 **Encrypt today. Survive tomorrow's quantum threat.**
 
 [Documentation](docs/) · [Examples](examples/) · [File Format Spec](docs/file_format.md) · [CLI Reference](docs/cli.md)
 
 </div>
