securepayload 1.0.0__py3-none-any.whl

securepayload/__init__.py

@@ -0,0 +1,124 @@
+"""
+SecurePayload — Python AES API payload encryption.
+
+Primary usage::
+
+    import securepayload
+
+    securepayload.bootstrap()
+    ciphertext = securepayload.encrypt({"order_no": "m123"})
+    payload = securepayload.decrypt(ciphertext)
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from .aes import Aes
+from .encryption_service import EncryptionService
+from .env import find_env_file, load_env
+from .exceptions import (
+    DecryptionError,
+    EncryptionError,
+    InvalidKeyError,
+    SecurityEncryptionError,
+)
+
+__version__ = "1.0.0"
+
+_service: EncryptionService | None = None
+
+
+def configure(
+    key: str | None = None,
+    *,
+    key_size: int = 128,
+    iteration_count: int = 8,
+    iv: str = "",
+    env_file: Path | str | None = None,
+) -> None:
+    """
+    Set the AES key used by ``encrypt`` and ``decrypt``.
+
+    If ``key`` is omitted, loads ``SECURITY_AES_KEY`` from the environment
+    (searching for ``.env`` when needed).
+    """
+    global _service
+
+    resolved = key
+    if not resolved:
+        load_env(env_file)
+        resolved = os.environ.get("SECURITY_AES_KEY")
+
+    if not resolved:
+        raise InvalidKeyError(
+            "AES key is not configured. Set SECURITY_AES_KEY in .env or call configure(key=...)."
+        )
+
+    _service = EncryptionService(
+        resolved,
+        key_size=key_size,
+        iteration_count=iteration_count,
+        iv=iv,
+    )
+
+
+def bootstrap(
+    env_file: Path | str | None = None,
+    *,
+    key: str | None = None,
+    key_size: int = 128,
+    iteration_count: int = 8,
+    iv: str = "",
+) -> str:
+    """
+    Load ``.env`` and configure the module in one step.
+
+    If ``env_file`` is omitted, searches upward from the current working directory
+    for a ``.env`` file. Returns the configured key.
+    """
+    if key is None:
+        load_env(env_file)
+        key = os.environ.get("SECURITY_AES_KEY")
+    if not key:
+        raise InvalidKeyError(
+            "AES key is not configured. Set SECURITY_AES_KEY in .env or call bootstrap(key=...)."
+        )
+    configure(key=key, key_size=key_size, iteration_count=iteration_count, iv=iv)
+    return key
+
+
+def _get_service() -> EncryptionService:
+    if _service is None:
+        configure()
+    assert _service is not None
+    return _service
+
+
+def encrypt(data: dict | list | str) -> str:
+    """Encrypt a payload to a Base64 AES ciphertext string."""
+    return _get_service().encrypt(data)
+
+
+def decrypt(encrypted_data: Any) -> Any:
+    """Decrypt a Base64 ciphertext string or pass through dict/list payloads."""
+    return _get_service().decrypt(encrypted_data)
+
+
+__all__ = [
+    "Aes",
+    "EncryptionService",
+    "SecurityEncryptionError",
+    "EncryptionError",
+    "DecryptionError",
+    "InvalidKeyError",
+    "configure",
+    "bootstrap",
+    "encrypt",
+    "decrypt",
+    "load_env",
+    "find_env_file",
+    "__version__",
+]

securepayload/aes.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import copy
+import json
+from typing import Any, Callable, Iterable, Mapping, Sequence
+
+from Crypto.Cipher import AES
+
+from .exceptions import DecryptionError, EncryptionError, InvalidKeyError, SecurityEncryptionError
+
+_JSON_SEPARATORS = (",", ":")
+
+
+def prepare_key(key: str, key_size: int = 128) -> bytes:
+    if not key:
+        raise InvalidKeyError("AES key must be a non-empty string.")
+
+    byte_len = key_size // 8
+    raw = key.encode("utf-8")
+
+    if len(raw) < byte_len:
+        return raw.ljust(byte_len, b"\0")
+    if len(raw) > byte_len:
+        return raw[:byte_len]
+    return raw
+
+
+def _pkcs7_pad(data: bytes, block_size: int = 16) -> bytes:
+    pad_len = block_size - (len(data) % block_size)
+    return data + bytes([pad_len] * pad_len)
+
+
+def _pkcs7_unpad(data: bytes, block_size: int = 16) -> bytes:
+    if not data:
+        raise DecryptionError("Cannot unpad empty ciphertext.")
+    pad_len = data[-1]
+    if pad_len < 1 or pad_len > block_size:
+        raise DecryptionError("Invalid PKCS#7 padding.")
+    if data[-pad_len:] != bytes([pad_len] * pad_len):
+        raise DecryptionError("Invalid PKCS#7 padding bytes.")
+    return data[:-pad_len]
+
+
+def _to_json(data: Any) -> str:
+    return json.dumps(data, separators=_JSON_SEPARATORS, ensure_ascii=False)
+
+
+class Aes:
+    def __init__(
+        self,
+        key: str,
+        *,
+        key_size: int = 128,
+        iteration_count: int = 8,
+        iv: str = "",
+    ) -> None:
+        # iteration_count and iv are accepted for API compatibility; ECB ignores IV.
+        self.key_size = key_size
+        self.iteration_count = iteration_count
+        self.iv = iv
+        self.key = key
+        self._key_bytes = prepare_key(key, key_size)
+
+    def set_new_key(self, iv: str, key: str) -> tuple[str, str]:
+        """Update IV and key. Empty IV is allowed (ECB mode does not use IV)."""
+        if not key:
+            raise InvalidKeyError("Invalid key")
+        self.iv = iv
+        self.key = key
+        self._key_bytes = prepare_key(key, self.key_size)
+        return self.iv, self.key
+
+    def obj_copy(self, obj: Any) -> Any:
+        """Deep copy helper used by ``obj_pipe``."""
+        return copy.deepcopy(obj)
+
+    def obj_pipe(
+        self,
+        obj: Mapping[str, Any],
+        mode: int,
+        props: Iterable[str],
+    ) -> dict[str, Any]:
+        """Encrypt (mode > 0) or decrypt (mode <= 0) selected object properties."""
+        result = dict(self.obj_copy(obj))
+        for prop in props:
+            if prop not in obj:
+                continue
+            result[prop] = self.encrypt(obj[prop]) if mode > 0 else self.decrypt(obj[prop])
+        return result
+
+    def _transform(
+        self,
+        data: Any,
+        *,
+        props: Sequence[str] | None,
+        pipe_mode: int,
+        on_scalar: Callable[[str], str],
+        error_cls: type[SecurityEncryptionError],
+        action: str,
+    ) -> Any:
+        if isinstance(data, Mapping):
+            if props:
+                return self.obj_pipe(data, pipe_mode, props)
+            return on_scalar(_to_json(data))
+        if isinstance(data, (list, tuple)):
+            if props:
+                return [self.obj_pipe(item, pipe_mode, props) for item in data]
+            return on_scalar(_to_json(data))
+        if isinstance(data, str):
+            return on_scalar(data)
+        if isinstance(data, int):
+            return on_scalar(str(data))
+        raise error_cls(f"Unsupported {action} input type: {type(data).__name__}")
+
+    def encrypt(self, data: Any, props: Sequence[str] | None = None) -> Any:
+        """Encrypt strings, numbers, dicts, or lists."""
+        return self._transform(
+            data,
+            props=props,
+            pipe_mode=1,
+            on_scalar=self.do_encrypt,
+            error_cls=EncryptionError,
+            action="encrypt",
+        )
+
+    def decrypt(self, data: Any, props: Sequence[str] | None = None) -> Any:
+        """Decrypt strings, numbers, dicts, or lists."""
+        return self._transform(
+            data,
+            props=props,
+            pipe_mode=0,
+            on_scalar=self.do_decrypt,
+            error_cls=DecryptionError,
+            action="decrypt",
+        )
+
+    def do_encrypt(self, plain_text: str) -> str:
+        """Encrypt plaintext and return Base64 ciphertext."""
+        try:
+            cipher = AES.new(self._key_bytes, AES.MODE_ECB)
+            padded = _pkcs7_pad(plain_text.encode("utf-8"))
+            encrypted = cipher.encrypt(padded)
+            return base64.b64encode(encrypted).decode("ascii")
+        except SecurityEncryptionError:
+            raise
+        except (TypeError, ValueError, UnicodeError) as exc:
+            raise EncryptionError("Encryption failed.") from exc
+
+    def do_decrypt(self, cipher_text: str, key: str | None = None, iv: str | None = None) -> str:
+        """
+        Decrypt Base64 ciphertext.
+
+        ``key`` and ``iv`` are optional overrides; only ``key`` is applied when
+        provided. ECB mode ignores IV.
+        """
+        _ = iv  # ECB mode does not use IV.
+        try:
+            key_bytes = self._key_bytes if key is None else prepare_key(key, self.key_size)
+            raw = base64.b64decode(cipher_text, validate=True)
+            if len(raw) % 16 != 0:
+                raise DecryptionError("Ciphertext length must be a multiple of the AES block size.")
+            cipher = AES.new(key_bytes, AES.MODE_ECB)
+            decrypted = cipher.decrypt(raw)
+            return _pkcs7_unpad(decrypted).decode("utf-8")
+        except SecurityEncryptionError:
+            raise
+        except (binascii.Error, TypeError, ValueError, UnicodeError) as exc:
+            raise DecryptionError("Decryption failed.") from exc

securepayload/encryption_service.py

@@ -0,0 +1,59 @@
+"""High-level encryption service for API payloads."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .aes import Aes
+
+
+class EncryptionService:
+    """
+    Encrypt and decrypt API payloads using AES-128-ECB.
+
+    Provide your own AES key (16 characters for AES-128) to encrypt/decrypt
+    payloads exchanged with APIs.
+    """
+
+    def __init__(
+        self,
+        key: str,
+        *,
+        key_size: int = 128,
+        iteration_count: int = 8,
+        iv: str = "",
+    ) -> None:
+        self._aes = Aes(
+            key,
+            key_size=key_size,
+            iteration_count=iteration_count,
+            iv=iv,
+        )
+
+    def decrypt(self, encrypted_data: Any) -> Any:
+        """
+        Decrypt AES payload.
+
+        - dict/list: returned unchanged (already decoded)
+        - str: decrypted and JSON-decoded when possible; raw string otherwise
+        - other: ``None``
+        """
+        if isinstance(encrypted_data, (dict, list)):
+            return encrypted_data
+
+        if isinstance(encrypted_data, str):
+            plaintext = self._aes.decrypt(encrypted_data)
+            try:
+                return json.loads(plaintext)
+            except json.JSONDecodeError:
+                return plaintext
+
+        return None
+
+    def encrypt(self, data: dict | list | str) -> str:
+        """Encrypt data to a Base64 AES string."""
+        return self._aes.encrypt(data)
+
+    Decrypt = decrypt
+    Encrypt = encrypt

securepayload/env.py

@@ -0,0 +1,56 @@
+"""Load environment variables from a .env file."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def find_env_file(start: Path | None = None) -> Path | None:
+    """Walk upward from ``start`` (default: cwd) looking for a ``.env`` file."""
+    current = (start or Path.cwd()).resolve()
+    for directory in (current, *current.parents):
+        candidate = directory / ".env"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def load_env(env_file: Path | str | None = None) -> bool:
+    """
+    Load variables from a ``.env`` file into ``os.environ``.
+
+    Uses python-dotenv when installed; otherwise parses the file directly.
+    When ``env_file`` is omitted, searches upward from the current working directory.
+    Returns ``True`` if a file was found and loaded.
+    """
+    if env_file is not None:
+        path = Path(env_file)
+    else:
+        found = find_env_file()
+        if found is None:
+            return False
+        path = found
+
+    if not path.is_file():
+        return False
+
+    try:
+        from dotenv import load_dotenv
+
+        load_dotenv(path)
+        return True
+    except ImportError:
+        pass
+
+    for line in path.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or "=" not in stripped:
+            continue
+        key, _, value = stripped.partition("=")
+        key = key.strip()
+        value = value.strip().strip('"').strip("'")
+        if key:
+            os.environ.setdefault(key, value)
+
+    return True

securepayload/exceptions.py

@@ -0,0 +1,14 @@
+class SecurityEncryptionError(Exception):
+    """Base exception for encryption package errors."""
+
+
+class InvalidKeyError(SecurityEncryptionError):
+    """Raised when the AES key is missing or invalid."""
+
+
+class EncryptionError(SecurityEncryptionError):
+    """Raised when encryption fails."""
+
+
+class DecryptionError(SecurityEncryptionError):
+    """Raised when decryption fails."""

securepayload/vectors.py

@@ -0,0 +1,9 @@
+"""Shared known ciphertext vectors for tests and examples."""
+
+KNOWN_STRING_PLAIN = {"test": "hello"}
+KNOWN_STRING_CIPHER = "4f58KzglCzu10lH/7VxEy+tBHZ/TaMAkHQSH/SnDBEI="
+
+KNOWN_ORDER_PLAIN = {"order_no": "m123"}
+KNOWN_ORDER_CIPHER = "3zBcPh7pTI8VHlNt6MdfQxHTv+BOkN5Gg5gmBxzQ07g="
+
+SAMPLE_KEY = "abcdefghijklmnop"

securepayload-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+securepayload/__init__.py,sha256=OeB0UOLhmy9KR7GK48oufMs8b7yXL_pe9YXaSr7VZfo,2918
+securepayload/aes.py,sha256=hJha9JxEfauiFUTjDvp5CxM23z6WiRzcb9OyGM5eHPc,5788
+securepayload/encryption_service.py,sha256=9lJG39UXZocGwMqwnWfYKKbhJfR0coPk5OAl3FIjlqo,1473
+securepayload/env.py,sha256=Qwt9TWjmov696f7I4VpDd5Eb8Y8ngI3NNoQlYPosb8U,1584
+securepayload/exceptions.py,sha256=ASrQzgzEClFwDerzJfx8hSoGau3giY2ZG4te_8XEWkY,385
+securepayload/vectors.py,sha256=Zg_w50lcWHjCgB5XgzBOBL2aFS52TMBVZT5fV1QTyP8,314
+securepayload-1.0.0.dist-info/METADATA,sha256=wl6QgBPZZqiTrq_n9WR4UMt8iAibg5Cnr4kKuTC0XOE,7996
+securepayload-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+securepayload-1.0.0.dist-info/top_level.txt,sha256=6q4BgFB9aqOpCkzymWB7qY-mdEPEr51VF2xuX2suCE8,14
+securepayload-1.0.0.dist-info/RECORD,,

securepayload-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

securepayload-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+securepayload