securepayload 1.0.0__tar.gz

securepayload-1.0.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: securepayload
+Version: 1.0.0
+Summary: SecurePayload — Python AES encryption library for API payloads. Encrypt and decrypt with securepayload.encrypt() and securepayload.decrypt().
+Author-email: zfhassaan <zfhassaan@gmail.com>
+License: Proprietary
+Project-URL: Homepage, https://github.com/zfhassaan/securepayload
+Project-URL: Documentation, https://github.com/zfhassaan/securepayload#readme
+Project-URL: Source, https://github.com/zfhassaan/securepayload
+Project-URL: Issues, https://github.com/zfhassaan/securepayload/issues
+Keywords: aes,aes-encryption,api-payload,cryptography,encryption,payload-encryption,python-security,secure-payload,webhook-encryption
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pycryptodome>=3.20.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+
+<p align="center">
+  <img src="assets/banner.png" alt="SecurePayload — Python AES API Payload Encryption Library" width="100%" />
+</p>
+
+<p align="center">
+  <img src="assets/logo.png" alt="SecurePayload logo" width="50" />
+</p>
+
+<h1 align="center">SecurePayload</h1>
+
+<p align="center">
+  <strong>Python AES encryption library for secure API payload handling</strong>
+</p>
+
+<p align="center">
+  Encrypt and decrypt JSON API payloads, webhook bodies, and request data with a simple two-call API —
+  <code>securepayload.encrypt()</code> and <code>securepayload.decrypt()</code>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#usage">Usage</a> •
+  <a href="#api-reference">API Reference</a> •
+  <a href="#testing">Testing</a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.9+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.9+" />
+  <img src="https://img.shields.io/badge/AES--128--ECB-14b8a6?style=flat-square" alt="AES-128-ECB" />
+  <img src="https://img.shields.io/badge/license-Proprietary-64748b?style=flat-square" alt="License" />
+</p>
+
+---
+
+## Overview
+
+**SecurePayload** is a lightweight Python cryptography library built for developers who need to **encrypt API request bodies** and **decrypt encrypted webhook or HTTP payloads**. It uses AES-128-ECB with PKCS#7 padding and Base64 output — compatible with existing encrypted API integrations.
+
+Ideal for:
+
+- Python microservices sending encrypted API requests
+- Webhook receivers decrypting incoming payloads
+- Background workers and ETL pipelines handling secure JSON data
+- Integration scripts bridging encrypted API endpoints
+
+```python
+import securepayload
+
+securepayload.bootstrap()
+
+encrypted = securepayload.encrypt({"order_no": "m123", "channel": "CARD"})
+decrypted = securepayload.decrypt(encrypted)
+```
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Simple API** | `securepayload.encrypt()` and `securepayload.decrypt()` — minimal boilerplate |
+| **API payload ready** | JSON dicts and lists encrypted automatically |
+| **Environment-based keys** | Configure via `securepayload.bootstrap()` or `configure(key=...)` |
+| **Selective field encryption** | `Aes.obj_pipe()` for encrypting individual record fields |
+| **Typed exceptions** | `InvalidKeyError`, `EncryptionError`, `DecryptionError` |
+
+---
+
+## Requirements
+
+- Python **3.9+**
+- [PyCryptodome](https://pycryptodome.readthedocs.io/)
+- [python-dotenv](https://github.com/theskumar/python-dotenv)
+
+---
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install securepayload
+```
+
+### From source (development)
+
+```bash
+git clone https://github.com/zfhassaan/securepayload.git
+cd securepayload
+python -m venv env
+
+# Windows
+env\Scripts\activate
+
+# macOS / Linux
+source env/bin/activate
+
+pip install -e ".[dev]"
+```
+
+### Configure your AES key
+
+Create a `.env` file (or set the variable in your environment):
+
+```env
+SECURITY_AES_KEY=your-16-char-key
+```
+
+> **Security:** Never commit production keys. Keep `.env` out of version control.
+
+---
+
+## Quick start
+
+```python
+import securepayload
+
+securepayload.bootstrap()  # loads .env and configures the key
+
+payload = {"order_no": "26168785012837", "channel": "CARD"}
+
+encrypted = securepayload.encrypt(payload)
+decrypted = securepayload.decrypt(encrypted)
+
+print(encrypted)   # Base64 ciphertext
+print(decrypted)   # Original dict
+```
+
+```bash
+python examples/basic_usage.py
+```
+
+---
+
+## Usage
+
+### Encrypt and decrypt API payloads
+
+```python
+import securepayload
+
+# Load key from .env (searches upward from cwd)
+securepayload.bootstrap()
+
+# Or pass key explicitly
+securepayload.configure(key="your-16-char-key")
+
+# Encrypt JSON payload → Base64 string
+ciphertext = securepayload.encrypt({"order_no": "m123", "channel": "CARD"})
+
+# Decrypt → dict (auto JSON-parsed)
+data = securepayload.decrypt(ciphertext)
+```
+
+| Input to `decrypt()` | Result |
+|----------------------|--------|
+| Base64 `str` | Decrypted; JSON-parsed when valid JSON |
+| `dict` / `list` | Returned unchanged |
+| Other | `None` |
+
+### HTTP integration
+
+```python
+import os
+import requests
+import securepayload
+
+securepayload.configure(key=os.environ["SECURITY_AES_KEY"])
+
+body = securepayload.encrypt({"event": "order.updated", "order_no": "m123"})
+requests.post("https://api.example.com/webhook", data=body)
+```
+
+### Error handling
+
+```python
+import securepayload
+from securepayload.exceptions import DecryptionError, InvalidKeyError
+
+try:
+    securepayload.configure(key="")
+except InvalidKeyError:
+    ...
+
+try:
+    securepayload.decrypt("invalid-ciphertext")
+except DecryptionError:
+    ...
+```
+
+### Advanced: selective field encryption
+
+```python
+from securepayload import Aes
+
+aes = Aes(key="your-16-char-key")
+record = {"name": "public", "token": "secret-value"}
+sealed = aes.obj_pipe(record, mode=1, props=["token"])
+```
+
+---
+
+## Examples
+
+| Script | Description |
+|--------|-------------|
+| `examples/basic_usage.py` | Encrypt/decrypt demo |
+| `examples/vector_test.py` | Known ciphertext vector validation |
+| `examples/run_tests.py` | Runs the pytest suite |
+
+```bash
+python examples/basic_usage.py
+python examples/vector_test.py
+```
+
+---
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```
+
+---
+
+## Cryptographic specification
+
+| Setting | Value |
+|---------|-------|
+| Algorithm | AES-128-ECB |
+| Padding | PKCS#7 |
+| Output | Base64 |
+| Key | 16-byte UTF-8 string (padded/truncated) |
+
+### Known test vectors
+
+| Plaintext | Ciphertext |
+|-----------|------------|
+| `{"test":"hello"}` | `4f58KzglCzu10lH/7VxEy+tBHZ/TaMAkHQSH/SnDBEI=` |
+| `{"order_no":"m123"}` | `3zBcPh7pTI8VHlNt6MdfQxHTv+BOkN5Gg5gmBxzQ07g=` |
+
+---
+
+## Project structure
+
+```
+├── assets/
+│   ├── banner.png          # README banner
+│   └── logo.png            # Project logo
+├── securepayload/          # Main package
+│   ├── __init__.py         # securepayload.encrypt / decrypt
+│   ├── aes.py
+│   ├── encryption_service.py
+│   └── exceptions.py
+├── examples/
+├── tests/
+└── docs/
+    └── API.md
+```
+
+---
+
+## Security considerations
+
+- **ECB mode** is retained for compatibility with existing encrypted API systems.
+- Use `.env` locally and a secrets manager in production.
+- Rotate keys through your deployment pipeline.
+
+---
+
+## Documentation
+
+- [API reference](docs/API.md)
+- Repository: [github.com/zfhassaan/securepayload](https://github.com/zfhassaan/securepayload)
+
+---
+
+## License
+
+Proprietary — internal tooling. Use according to your organization's policies.

securepayload-1.0.0/README.md

@@ -0,0 +1,282 @@
+<p align="center">
+  <img src="assets/banner.png" alt="SecurePayload — Python AES API Payload Encryption Library" width="100%" />
+</p>
+
+<p align="center">
+  <img src="assets/logo.png" alt="SecurePayload logo" width="50" />
+</p>
+
+<h1 align="center">SecurePayload</h1>
+
+<p align="center">
+  <strong>Python AES encryption library for secure API payload handling</strong>
+</p>
+
+<p align="center">
+  Encrypt and decrypt JSON API payloads, webhook bodies, and request data with a simple two-call API —
+  <code>securepayload.encrypt()</code> and <code>securepayload.decrypt()</code>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#usage">Usage</a> •
+  <a href="#api-reference">API Reference</a> •
+  <a href="#testing">Testing</a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.9+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.9+" />
+  <img src="https://img.shields.io/badge/AES--128--ECB-14b8a6?style=flat-square" alt="AES-128-ECB" />
+  <img src="https://img.shields.io/badge/license-Proprietary-64748b?style=flat-square" alt="License" />
+</p>
+
+---
+
+## Overview
+
+**SecurePayload** is a lightweight Python cryptography library built for developers who need to **encrypt API request bodies** and **decrypt encrypted webhook or HTTP payloads**. It uses AES-128-ECB with PKCS#7 padding and Base64 output — compatible with existing encrypted API integrations.
+
+Ideal for:
+
+- Python microservices sending encrypted API requests
+- Webhook receivers decrypting incoming payloads
+- Background workers and ETL pipelines handling secure JSON data
+- Integration scripts bridging encrypted API endpoints
+
+```python
+import securepayload
+
+securepayload.bootstrap()
+
+encrypted = securepayload.encrypt({"order_no": "m123", "channel": "CARD"})
+decrypted = securepayload.decrypt(encrypted)
+```
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Simple API** | `securepayload.encrypt()` and `securepayload.decrypt()` — minimal boilerplate |
+| **API payload ready** | JSON dicts and lists encrypted automatically |
+| **Environment-based keys** | Configure via `securepayload.bootstrap()` or `configure(key=...)` |
+| **Selective field encryption** | `Aes.obj_pipe()` for encrypting individual record fields |
+| **Typed exceptions** | `InvalidKeyError`, `EncryptionError`, `DecryptionError` |
+
+---
+
+## Requirements
+
+- Python **3.9+**
+- [PyCryptodome](https://pycryptodome.readthedocs.io/)
+- [python-dotenv](https://github.com/theskumar/python-dotenv)
+
+---
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install securepayload
+```
+
+### From source (development)
+
+```bash
+git clone https://github.com/zfhassaan/securepayload.git
+cd securepayload
+python -m venv env
+
+# Windows
+env\Scripts\activate
+
+# macOS / Linux
+source env/bin/activate
+
+pip install -e ".[dev]"
+```
+
+### Configure your AES key
+
+Create a `.env` file (or set the variable in your environment):
+
+```env
+SECURITY_AES_KEY=your-16-char-key
+```
+
+> **Security:** Never commit production keys. Keep `.env` out of version control.
+
+---
+
+## Quick start
+
+```python
+import securepayload
+
+securepayload.bootstrap()  # loads .env and configures the key
+
+payload = {"order_no": "26168785012837", "channel": "CARD"}
+
+encrypted = securepayload.encrypt(payload)
+decrypted = securepayload.decrypt(encrypted)
+
+print(encrypted)   # Base64 ciphertext
+print(decrypted)   # Original dict
+```
+
+```bash
+python examples/basic_usage.py
+```
+
+---
+
+## Usage
+
+### Encrypt and decrypt API payloads
+
+```python
+import securepayload
+
+# Load key from .env (searches upward from cwd)
+securepayload.bootstrap()
+
+# Or pass key explicitly
+securepayload.configure(key="your-16-char-key")
+
+# Encrypt JSON payload → Base64 string
+ciphertext = securepayload.encrypt({"order_no": "m123", "channel": "CARD"})
+
+# Decrypt → dict (auto JSON-parsed)
+data = securepayload.decrypt(ciphertext)
+```
+
+| Input to `decrypt()` | Result |
+|----------------------|--------|
+| Base64 `str` | Decrypted; JSON-parsed when valid JSON |
+| `dict` / `list` | Returned unchanged |
+| Other | `None` |
+
+### HTTP integration
+
+```python
+import os
+import requests
+import securepayload
+
+securepayload.configure(key=os.environ["SECURITY_AES_KEY"])
+
+body = securepayload.encrypt({"event": "order.updated", "order_no": "m123"})
+requests.post("https://api.example.com/webhook", data=body)
+```
+
+### Error handling
+
+```python
+import securepayload
+from securepayload.exceptions import DecryptionError, InvalidKeyError
+
+try:
+    securepayload.configure(key="")
+except InvalidKeyError:
+    ...
+
+try:
+    securepayload.decrypt("invalid-ciphertext")
+except DecryptionError:
+    ...
+```
+
+### Advanced: selective field encryption
+
+```python
+from securepayload import Aes
+
+aes = Aes(key="your-16-char-key")
+record = {"name": "public", "token": "secret-value"}
+sealed = aes.obj_pipe(record, mode=1, props=["token"])
+```
+
+---
+
+## Examples
+
+| Script | Description |
+|--------|-------------|
+| `examples/basic_usage.py` | Encrypt/decrypt demo |
+| `examples/vector_test.py` | Known ciphertext vector validation |
+| `examples/run_tests.py` | Runs the pytest suite |
+
+```bash
+python examples/basic_usage.py
+python examples/vector_test.py
+```
+
+---
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```
+
+---
+
+## Cryptographic specification
+
+| Setting | Value |
+|---------|-------|
+| Algorithm | AES-128-ECB |
+| Padding | PKCS#7 |
+| Output | Base64 |
+| Key | 16-byte UTF-8 string (padded/truncated) |
+
+### Known test vectors
+
+| Plaintext | Ciphertext |
+|-----------|------------|
+| `{"test":"hello"}` | `4f58KzglCzu10lH/7VxEy+tBHZ/TaMAkHQSH/SnDBEI=` |
+| `{"order_no":"m123"}` | `3zBcPh7pTI8VHlNt6MdfQxHTv+BOkN5Gg5gmBxzQ07g=` |
+
+---
+
+## Project structure
+
+```
+├── assets/
+│   ├── banner.png          # README banner
+│   └── logo.png            # Project logo
+├── securepayload/          # Main package
+│   ├── __init__.py         # securepayload.encrypt / decrypt
+│   ├── aes.py
+│   ├── encryption_service.py
+│   └── exceptions.py
+├── examples/
+├── tests/
+└── docs/
+    └── API.md
+```
+
+---
+
+## Security considerations
+
+- **ECB mode** is retained for compatibility with existing encrypted API systems.
+- Use `.env` locally and a secrets manager in production.
+- Rotate keys through your deployment pipeline.
+
+---
+
+## Documentation
+
+- [API reference](docs/API.md)
+- Repository: [github.com/zfhassaan/securepayload](https://github.com/zfhassaan/securepayload)
+
+---
+
+## License
+
+Proprietary — internal tooling. Use according to your organization's policies.

securepayload-1.0.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "securepayload"
+version = "1.0.0"
+description = "SecurePayload — Python AES encryption library for API payloads. Encrypt and decrypt with securepayload.encrypt() and securepayload.decrypt()."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+authors = [{ name = "zfhassaan", email = "zfhassaan@gmail.com" }]
+keywords = [
+    "aes",
+    "aes-encryption",
+    "api-payload",
+    "cryptography",
+    "encryption",
+    "payload-encryption",
+    "python-security",
+    "secure-payload",
+    "webhook-encryption",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security :: Cryptography",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "pycryptodome>=3.20.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/zfhassaan/securepayload"
+Documentation = "https://github.com/zfhassaan/securepayload#readme"
+Source = "https://github.com/zfhassaan/securepayload"
+Issues = "https://github.com/zfhassaan/securepayload/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["securepayload*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]