iqcc-shared 0.1.0__tar.gz

iqcc_shared-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+__pycache__
+.venv
+.mypy_cache
+simulator.tar
+/deployment/certs*
+dist
+/deployment_qolab
+/test/with_qbridge
+*_qolab*
+.ruff_cache
+/test/demo
+playground
+/test/with_qbridge
+/test/with_compiler
+*.ipynb
+**/key_config.yaml
+*.pdf
+*.tar
+iqcc-cloud-client/test
+.coverage
+.pytest_cache
+*.jsonl
+development_log/
+*.whl

iqcc_shared-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: iqcc-shared
+Version: 0.1.0
+Summary: Hybrid cryptographic utilities: ML-KEM-768 key encapsulation, ML-DSA-65 signing, AES-256-GCM payload encryption, and msgpack serialization
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=48.0.0
+Requires-Dist: msgpack>=1.0.8

iqcc_shared-0.1.0/README.md

@@ -0,0 +1,248 @@
+# `iqcc-shared` - Symmetric Encryption with Post-Quantum Key Exchange
+
+## Overview
+`iqcc-shared` is a lightweight, shared Python module providing hybrid encryption and automated key rotation utilities. It is used by both the `iqcc-cloud-client` SDK and the `worker` process to securely exchange payloads while ensuring confidentiality and per-field integrity via AES-256-GCM, with post-quantum ML-KEM-768 key encapsulation for session key exchange.
+
+All data serialization uses **[msgpack](https://msgpack.org/)** instead of JSON - providing compact binary encoding, native binary field support, and zero base64 overhead. The sole exception is public key exchange, where ML-KEM-768 public keys are shared as JSON strings to allow format-independent distribution.
+
+## Architecture & Data Flow
+
+```text
+[Worker]                          [Storage]                     [Client SDK]
+   │                                  │                              │
+   │ 1. Publishes Public Key Record   │                              │
+   │    (current + previous keys)     │                              │
+   │─────────────────────────────────►│                              │
+   │                                  │ 2. Fetches Public Key Record │
+   │                                  │◄─────────────────────────────│
+   │                                  │ 3. Generates AES-256-GCM     │
+   │                                  │    session key               │
+   │                                  │ 4. Encrypts target paths     │
+   │                                  │    in payload                │
+   │                                  │ 5. Encapsulates session key  │
+   │                                  │    with worker public key    │
+   │                                  │ 6. msgpack-serializes        │
+   │                                  │    full message              │
+   │ 7. Receives msgpack message      │                              │
+   │◄─────────────────────────────────│                              │
+   │ 8. Decapsulates session key      │                              │
+   │    with worker private key       │                              │
+   │ 9. Decrypts target paths         │                              │
+   │    (AES-GCM auth tag verified)   │                              │
+   │ 10. Processes payload            │                              │
+   │ 11. Encrypts results with        │                              │
+   │     same session key (symmetric) │                              │
+   │─────────────────────────────────►│                              │
+   │                                  │ 12. Decrypts with session    │
+   │                                  │     key (already known)      │
+```
+
+## Cryptographic Design
+| Component | Algorithm | Purpose |
+|-----------|-----------|---------|
+| **Asymmetric Key Encapsulation** | ML-KEM-768 (post-quantum) | Protects the symmetric session key during transit via key encapsulation |
+| **Symmetric Payload Encryption** | AES-256-GCM | Encrypts target payload fields; provides confidentiality + integrity via per-field authentication tags |
+| **Key Derivation/Nonce** | Cryptographically secure RNG (`os.urandom`) | Generates unique GCM nonces per operation |
+| **Serialization** | msgpack (strict mode) | Compact binary format with native binary fields; no base64 needed |
+
+> **Integrity model:** Each encrypted field carries its own AES-GCM authentication tag. On decryption, the tag is verified automatically - any tampering with ciphertext, nonce, or tag causes decryption to fail. Because the client and worker are in a trusted relationship (authenticated via API tokens), separate digital signatures are not needed.
+
+## Msgpack Security Hardening
+msgpack's default settings allow untrusted input to allocate arbitrary memory. This module enforces strict decode parameters to reduce attack surface:
+
+| Parameter | Value | Rationale |
+|-----------|-------|-----------|
+| `strict_map_key` | `True` | Rejects non-str/non-binary map keys; prevents deserialization confusion |
+| `max_str_len` | 20 MiB | Limits string field size; prevents memory exhaustion from oversized strings |
+| `max_bin_len` | 20 MiB | Limits binary field size; prevents memory exhaustion from oversized binary data |
+| `max_array_len` | 500,000 | Limits array nesting depth; prevents stack overflow from deeply nested arrays |
+| `max_map_len` | 100,000 | Limits map entries; prevents hash-flooding and memory exhaustion |
+| `max_ext_len` | 1,000 | Limits extension type usage; extension types are not used but guarded against |
+| `raw` | `False` | Auto-decodes strings to `str`; prevents raw `bytes` leakage into app logic |
+
+These limits are configurable via module-level constants but are **enforced by default** on all public API entry points that accept serialized input.
+
+## Key Management & Rotation
+The worker maintains a msgpack-serializable key record containing two public keys: `current` (actively used) and `previous` (overlap window for rotation). Each key entry includes a `key_id`, `public_key` (JSON-encoded string), and `expires_at` (ISO-8601 string). Public keys are stored as strings so they can be independently exchanged as JSON without msgpack coupling - other payloads remain msgpack-encoded as described below.
+
+### Record Structure
+```python
+{
+    "current": {
+        "key_id": "uuid-v4",
+        "public_key": "{...}",  # ML-KEM-768 public key as JSON string
+        "public_key_format": "ml-kem-768",
+        "expires_at": "2025-12-31T23:59:59Z"
+    },
+    "previous": {
+        "key_id": "uuid-v4",
+        "public_key": "{...}",  # ML-KEM-768 public key as JSON string
+        "public_key_format": "ml-kem-768",
+        "expires_at": "2025-06-30T23:59:59Z"
+    },
+    "rotation_policy": "auto",
+    "updated_at": "2025-01-15T10:00:00Z"
+}
+```
+
+## Core API Specification
+
+### 1. Key Record Creation & Rotation
+**Used by:** Worker
+**Signature:**
+```python
+def create_or_rotate_key_record(
+    existing_record: Optional[dict] = None,
+    validity_days: int = 180,
+    overlap_days: int = 30
+) -> tuple[dict, str | None]
+```
+**Behavior:**
+- If `existing_record` is `None`, generates a fresh `current` key and returns a new record paired with the corresponding ML-KEM-768 private key as a hex-encoded string.
+- If `existing_record` exists and `current.expires_at` is within the rotation window, generates a new key, shifts `current → previous`, updates expiry timestamps, and returns the rotated record paired with the new private key hex string.
+- If no rotation is needed, returns the existing record as-is with `None` for the private key.
+- Generates ML-KEM-768 key pairs using `cryptography.hazmat.primitives.asymmetric.mlkem.MLKEM768PrivateKey.generate()`.
+- Returns a tuple `(key_record, private_key_hex)` where `key_record` is a fully valid dict ready for publishing (`public_key` fields are JSON-encoded strings) and `private_key_hex` is a hex-encoded string (128 hex chars) of the ML-KEM-768 private key suitable for storage in Kubernetes secrets, or `None` if no new key was generated.
+
+---
+
+### 2. Encrypt Payload
+**Used by:** Client SDK (request) and Worker (response)
+**Signature:**
+```python
+def encrypt(
+    payload: dict,
+    paths: list[str],
+    target_public_key: PublicKey | None = None,
+    target_key_id: str = "",
+    session_key: bytes | None = None,
+) -> tuple[bytes, bytes]
+```
+**Behavior:**
+- Recursively traverses `payload` using dot-notation `paths` (supports `.*` wildcards for child matching).
+- **Generates the AES-256-GCM session key:**
+  - If `session_key` is provided, uses it directly (key reuse across request/response).
+  - If `target_public_key` is provided and `session_key` is `None`: encapsulates via ML-KEM-768 `public_key.encapsulate()`, the returned shared secret becomes the session key.
+  - If both are `None`: generates a fresh 32-byte key via `os.urandom(AES_KEY_SIZE)`.
+- For each matched value, encrypts using AES-256-GCM with the session key. The ciphertext, nonce, and authentication tag are stored as **native msgpack binary fields, no base64**.
+- **If `target_public_key` was provided:** the encapsulation ciphertext is recorded as `encapsulated_session_key` in metadata. `target_key_id` is also recorded.
+- **If `target_public_key` was `None`:** no key encapsulation occurs. The fields `encapsulated_session_key`, `target_public_key_id`, and `key_encapsulation_algorithm` are omitted from metadata. This is the *worker response* path, where the client already holds the session key from the initial request.
+- Builds the full message dict with `encryption_metadata` and the modified `payload`.
+- **Serializes the message to raw msgpack bytes** using strict encoder settings.
+- Returns a tuple `(message_bytes, session_key)` where `message_bytes` is the final msgpack-serialized bytes ready for transmission, and `session_key` is the 32-byte AES key used (useful when no encapsulation occurred and the caller needs to store it for the response path).
+
+---
+
+### 3. Decrypt Payload
+**Used by:** Worker (decrypts initial client payload) **and** Client SDK (decrypts worker results)
+**Signature:**
+```python
+def decrypt(
+    message_bytes: bytes,
+    paths: list[str],
+    server_private_key: Optional[PrivateKey | str] = None,
+    session_key: Optional[bytes] = None,
+    max_msgpack_len: int = MSGPACK_DEFAULT_MAX_SIZE  # 20 MiB default
+) -> dict
+```
+**Behavior:**
+- **Validates message size** against `max_msgpack_len` before any deserialization (prevents memory exhaustion).
+- **Deserializes msgpack with strict security limits** (`strict_map_key=True`, bounded lengths).
+- Extracts `encryption_metadata`.
+- Resolves the AES-256-GCM session key using one of two methods:
+  - **`session_key` provided directly:** Uses it as-is. Typical for the **Client SDK decrypting worker results** (the worker replies without encapsulation because the client already holds the session key).
+  - **`server_private_key` provided and message contains encapsulation:** Decapsulates via `server_private_key.decapsulate(ciphertext)`. Typical for the **Worker decrypting the initial client payload**. `server_private_key` accepts either an `MLKEM768PrivateKey` object or a hex-encoded string (as returned by `create_or_rotate_key_record`).
+- Recursively traverses the payload using `paths` and decrypts matched values. Each field's AES-GCM authentication tag is verified automatically - tampered fields raise an exception.
+- Returns the fully decrypted `payload` dict ready for processing.
+
+## Message Format (msgpack-serialized dict)
+The wire format is a msgpack-encoded dict with this logical structure:
+
+```python
+{
+    b"encryption_metadata": {
+        b"version": b"1.0",
+        b"key_encapsulation_algorithm": b"ML-KEM-768",  # omitted when no encapsulation used
+        b"payload_encryption_algorithm": b"AES-256-GCM",
+        b"target_public_key_id": b"uuid-v4",             # omitted when target_public_key is None
+        b"encapsulated_session_key": <bytes>,            # ML-KEM-768 encapsulation ciphertext, omitted when no encapsulation
+        b"encrypted_paths": [b"auth.token", b"data.sensitive.*"],
+        b"timestamp": b"ISO-8601-timestamp"
+    },
+    b"payload": {
+        b"auth": {
+            b"token": {
+                b"encrypted": <bytes>,   # AES-256-GCM ciphertext
+                b"nonce": <bytes>,       # GCM nonce (native binary)
+                b"tag": <bytes>          # GCM auth tag (native binary)
+            }
+        },
+        b"data": {
+            b"public_info": b"unencrypted-string",
+            b"sensitive": {
+                b"field1": {
+                    b"encrypted": <bytes>,
+                    b"nonce": <bytes>,
+                    b"tag": <bytes>
+                },
+                b"field2": {
+                    b"encrypted": <bytes>,
+                    b"nonce": <bytes>,
+                    b"tag": <bytes>
+                }
+            }
+        }
+    }
+}
+```
+
+> All `bytes` fields above are stored as **native msgpack binary (bin 8/16/32)** - no base64 encoding/decoding overhead. When `target_public_key` is `None` (no encapsulation), `key_encapsulation_algorithm`, `target_public_key_id`, and `encapsulated_session_key` fields are **omitted** from `encryption_metadata`.
+
+## Implementation Roadmap
+1. **Scaffold Module**
+   - Create `iqcc-shared/pyproject.toml` with dependencies: `cryptography>=46.0.5`, `msgpack>=1.0.8`
+   - Create `src/iqcc_shared/__init__.py`, `src/iqcc_shared/crypto.py`, and `src/iqcc_shared/msgpack_utils.py`
+2. **Msgpack Serialization Layer**
+   - Define strict encode/decode constants and reusable helper functions in `msgpack_utils.py`
+   - Add size validation guards before all deserialization calls
+3. **Key Management**
+   - Implement ML-KEM-768 key generation; serialize public keys to JSON strings, private keys to hex strings
+   - Build `create_or_rotate_key_record()` with expiry/overlap logic
+   - Public keys stored as JSON strings for independent exchange; private keys hex-encoded for Kubernetes secrets compatibility
+4. **Path Traversal & Encryption/Decryption**
+   - Implement dot-notation path resolver with `.*` wildcard support
+   - Wrap AES-256-GCM operations (encrypt/decrypt with nonce & tag handling)
+5. **Hybrid Key Encapsulation & Encryption**
+   - Implement ML-KEM-768 session key encapsulation/decapsulation
+   - Assemble `encrypt()` and `decrypt()`
+6. **Testing**
+   - Unit tests for key rotation windows
+   - Integration tests for round-trip encrypt → verify → decrypt
+   - Path matching edge cases (nested dicts, lists, wildcards)
+   - **Msgpack security tests:** oversized payloads, invalid map keys, deeply nested structures
+7. **Wire into Client & Worker**
+   - Add path dependency to `webserver/pyproject.toml` and `iqcc-cloud-client/pyproject.toml`
+   - Import `from iqcc_shared.crypto import ...` in respective modules
+
+## Security Best Practices
+- ✅ **Post-quantum key encapsulation:** ML-KEM-768 provides quantum-resistant key encapsulation, protecting against future quantum computing attacks.
+- ✅ **Per-field integrity:** Each encrypted field carries an AES-GCM authentication tag, verified automatically on decryption. Tampered ciphertext or nonce causes immediate failure.
+- ✅ **Unique encapsulation:** ML-KEM-768 `encapsulate()` generates fresh randomness per call; never reuse ciphertexts with the same public key.
+- ✅ **Unique nonces:** AES-GCM nonces are generated per-field using CSPRNG; never reuse nonces with the same key.
+- ✅ **Key isolation:** Session keys are single-use per payload exchange; results reuse the same key only within the same session lifecycle.
+- ✅ **Rotation overlap:** `previous` key remains valid for `overlap_days` to ensure clients can finish in-flight requests during rotation.
+- ✅ **Secure key storage:** ML-KEM private keys must be loaded from secure volumes/HSMs; never committed to version control.
+- ✅ **Strict msgpack decoding:** All public-facing deserialization enforces `strict_map_key=True`, bounded lengths, and `raw=False` to prevent memory exhaustion and type confusion attacks.
+- ✅ **Message size validation:** Raw msgpack bytes are checked against a configurable max size **before** any deserialization attempt.
+- ✅ **No base64 overhead:** All cryptographic binary data (ciphertexts, nonces, tags) uses native msgpack binary fields, eliminating encoding ambiguity and reducing attack surface. ML-KEM-768 public keys are an exception - serialized as JSON strings for format-independent exchange.
+
+## Dependencies
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `cryptography` | `>=46.0.5` | ML-KEM-768, AES-256-GCM primitives |
+| `msgpack` | `>=1.0.8` | Compact binary serialization with strict decode modes |
+| `typing` | Python stdlib | Type hints (`Optional`, `dict`, `list`) |
+| `os` / `time` | Python stdlib | CSPRNG, timestamp handling |
+
+---
+*This module is designed to be framework-agnostic, testable in isolation, and easily integrated via `uv` path dependencies.*

iqcc_shared-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "iqcc-shared"
+version = "0.1.0"
+description = "Hybrid cryptographic utilities: ML-KEM-768 key encapsulation, ML-DSA-65 signing, AES-256-GCM payload encryption, and msgpack serialization"
+requires-python = ">=3.10"
+dependencies = [
+    "cryptography>=48.0.0",
+    "msgpack>=1.0.8",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

iqcc_shared-0.1.0/src/iqcc_shared/__init__.py

@@ -0,0 +1,67 @@
+"""iqcc-shared — Symmetric Encryption with Post-Quantum Key Exchange.
+
+Provides hybrid encryption (ML-KEM-768 + AES-256-GCM),
+automated key rotation, and strict msgpack serialization.
+
+Key features:
+  • Post-quantum key encapsulation (ML-KEM-768)
+  • AES-256-GCM symmetric payload encryption with per-field auth tags
+  • Dot-notation path resolver with wildcard (``.*``) support
+  • Strict msgpack serialization with security hardening
+  • Automated key rotation with overlap window
+"""
+
+__version__ = "0.1.0"
+
+# ── Public API ──────────────────────────────────────────────────────────
+
+from .crypto import (
+    KEY_ROTATION_WINDOW_DAYS,
+    create_or_rotate_key_record,
+    decrypt,
+    encrypt,
+    generate_mlkem_keypair,
+    get_mlkem_public_key_bytes,
+    load_mlkem_public_key,
+    mlkem_private_key_from_hex,
+    mlkem_private_key_to_hex,
+    mlkem_public_key_from_json,
+    mlkem_public_key_to_json,
+)
+from .msgpack_utils import (
+    MSGPACK_DEFAULT_MAX_SIZE,
+    MSGPACK_MAX_ARRAY_LEN,
+    MSGPACK_MAX_BIN_LEN,
+    MSGPACK_MAX_EXT_LEN,
+    MSGPACK_MAX_MAP_LEN,
+    MSGPACK_MAX_STR_LEN,
+    msgpack_decode,
+    msgpack_encode,
+    validate_msgpack_size,
+)
+
+__all__ = [
+    # Key management
+    "KEY_ROTATION_WINDOW_DAYS",
+    "create_or_rotate_key_record",
+    "generate_mlkem_keypair",
+    "get_mlkem_public_key_bytes",
+    "load_mlkem_public_key",
+    "mlkem_private_key_from_hex",
+    "mlkem_private_key_to_hex",
+    "mlkem_public_key_from_json",
+    "mlkem_public_key_to_json",
+    # Encryption / decryption
+    "encrypt",
+    "decrypt",
+    # Msgpack utilities
+    "MSGPACK_DEFAULT_MAX_SIZE",
+    "MSGPACK_MAX_ARRAY_LEN",
+    "MSGPACK_MAX_BIN_LEN",
+    "MSGPACK_MAX_EXT_LEN",
+    "MSGPACK_MAX_MAP_LEN",
+    "MSGPACK_MAX_STR_LEN",
+    "msgpack_decode",
+    "msgpack_encode",
+    "validate_msgpack_size",
+]