fastapi-payloadshield 1.0.0__tar.gz → 1.2.0__tar.gz

fastapi_payloadshield-1.2.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: fastapi_payloadshield
+Version: 1.2.0
+Summary: Pluggable FastAPI decorators for encrypting/decrypting request and response payloads
+Author-email: Ganesh Kandu <kanduganesh@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/PayloadShield/FastAPIPS
+Project-URL: Repository, https://github.com/PayloadShield/FastAPIPS.git
+Project-URL: Issues, https://github.com/PayloadShield/FastAPIPS/issues
+Keywords: fastapi,base64,crypto,encryption,decorator
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.68.0
+Requires-Dist: starlette>=0.19.0
+Requires-Dist: cryptography>=41.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
+Dynamic: license-file
+
+# FastAPI Payload Shield
+
+Pluggable FastAPI decorators for encrypting and decrypting request and
+response payloads. Configure your keys once, then annotate any route with
+`@PayloadShield.encrypt`, `@PayloadShield.decrypt`, or `@PayloadShield.crypt`.
+
+> **Breaking change (v3.0.0)**: the old `encrypt_response` /
+> `decrypt_request` / `crypto_middleware` decorators and the old
+> `PayloadShieldEnc("base64")` factory function have been removed. There is
+> no backward-compatible alias — see [Migrating to v3](#migrating-to-v3)
+> below.
+
+## Key Features
+
+- **Pluggable encryption**: base64, Fernet, AES-GCM-256, and Hybrid RSA+AES
+  ship out of the box; register your own with `register_handler(...)`.
+- **One-time key configuration**: `PayloadShieldEnc.init({...})` sets keys
+  globally for all decorators.
+- **Route-agnostic**: no changes needed to your route logic besides adding a
+  decorator.
+- **Async-friendly**: works with FastAPI's async route handlers.
+
+## Installation
+
+```bash
+pip install fastapi_payloadshield
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from fastapi_payloadshield import PayloadShield, PayloadShieldEnc
+
+# Configure encryption keys once, at startup.
+PayloadShieldEnc.init({
+    "Key": "my-symmetric-key",
+})
+
+app = FastAPI()
+
+@app.get("/api/data")
+@PayloadShield.encrypt("base64")
+async def get_data():
+    return {"message": "hello", "data": "world"}
+
+@app.post("/api/process")
+@PayloadShield.decrypt("base64")
+async def process_data(data: dict):
+    return {"received": data, "status": "success"}
+
+@app.post("/api/secure")
+@PayloadShield.crypt("base64")
+async def secure_endpoint(data: dict):
+    return {"processed": data}
+```
+
+## Initialization: `PayloadShieldEnc.init(...)`
+
+Call once before serving requests. Every decorator reads this shared
+configuration at call time.
+
+```python
+PayloadShieldEnc.init({
+    "Key": key,               # symmetric key: fernet, aes-gcm-256
+    "PrivateKey": "string",   # RSA/hybrid private key (file path or PEM content)
+    "PublicKey": "string",    # RSA/hybrid public key (file path or PEM content)
+})
+```
+
+| Field | Used by | Accepts |
+|---|---|---|
+| `Key` | `fernet`, `aes-gcm-256` | Raw key string. `aes-gcm-256` requires the key to resolve to exactly 32 bytes (UTF-8 or base64 encoded). |
+| `PrivateKey` | `rsa-hybrid` (decrypt) | File path to a PEM file, or the raw PEM content. |
+| `PublicKey` | `rsa-hybrid` (encrypt) | File path to a PEM file, or the raw PEM content. |
+
+Only set the fields required by the encryption types you actually use.
+
+## Decorators
+
+All three live on the `PayloadShield` class and take an `encryption_type`
+(default `"base64"`).
+
+### `@PayloadShield.encrypt(encryption_type)`
+
+Encrypts the response payload only.
+
+```python
+@app.get("/api/users")
+@PayloadShield.encrypt("base64")
+async def get_users():
+    return [{"id": 1, "name": "Alice"}]
+
+# Response: {"encrypted": "W3siaWQiOiAxLCAibmFtZSI6ICJBbGljZSJ9XQ=="}
+```
+
+### `@PayloadShield.decrypt(encryption_type)`
+
+Decrypts the request payload only; the route receives the decrypted dict.
+
+```python
+@app.post("/api/login")
+@PayloadShield.decrypt("base64")
+async def login(credentials: dict):
+    return {"status": "success"}
+
+# Expects: {"encrypted": "base64_encoded_json"}
+```
+
+### `@PayloadShield.crypt(encryption_type)`
+
+Decrypts the request and encrypts the response.
+
+```python
+@app.post("/api/secure")
+@PayloadShield.crypt("base64")
+async def secure_endpoint(data: dict):
+    return {"processed": data}
+
+# Expects: {"encrypted": "encrypted_data"}
+# Returns: {"encrypted": "encrypted_data"}
+```
+
+## Built-in Encryption Handlers
+
+| Name | Algorithm | Keys required | Security |
+|---|---|---|---|
+| `base64` | Base64 encoding | none | None — obfuscation only |
+| `fernet` | Fernet (AES-128-CBC + HMAC) | `Key` | Symmetric, authenticated |
+| `aes-gcm-256` | AES-256-GCM | `Key` (32 bytes) | Symmetric, authenticated |
+| `rsa-hybrid` | RSA-OAEP + AES-256-GCM | `PublicKey` (encrypt), `PrivateKey` (decrypt) | Asymmetric/hybrid |
+
+## Custom Handlers
+
+Implement `EncryptionHandler` and register it — every decorator can then
+use it by name.
+
+```python
+from typing import Any, Dict, Optional
+from fastapi_payloadshield import EncryptionHandler, register_handler, PayloadShield
+
+class MyHandler(EncryptionHandler):
+    def encode(self, data: Any, config: Optional[Dict[str, Any]] = None) -> str:
+        ...
+
+    def decode(self, encoded_data: str, config: Optional[Dict[str, Any]] = None) -> Any:
+        ...
+
+register_handler("my-handler", MyHandler())
+
+@app.post("/api/custom")
+@PayloadShield.crypt("my-handler")
+async def custom_endpoint(data: dict):
+    return data
+```
+
+`config` is the dict returned by `PayloadShieldEnc.get_config()` — pull out
+whatever keys your handler needs (`Key`, `PrivateKey`, `PublicKey`).
+
+## How It Works
+
+**Request decryption**: client sends `{"encrypted": "..."}` → decorator
+decodes it with the configured handler → route receives the plain dict.
+
+**Response encryption**: route returns a dict → decorator encodes it with
+the configured handler → client receives `{"encrypted": "..."}`.
+
+## Errors
+
+| Situation | Behavior |
+|---|---|
+| Request decryption fails | `400` response: `{"error": "Failed to decrypt request: ..."}` |
+| Unknown `encryption_type` | `ValueError` raised when the decorator is applied: `Encryption handler '<name>' not found. Available handlers: ...` |
+| Missing required key (e.g. no `Key` set for `fernet`) | `ValueError` raised when encoding/decoding: `... requires 'Key' to be set via PayloadShieldEnc.init(...)` |
+
+## Migrating to v3
+
+| Removed (v2) | Replacement (v3) |
+|---|---|
+| `PayloadShieldEnc("base64")` (decorator factory) | `PayloadShield.encrypt("base64")` |
+| `PayloadShieldDec("base64")` | `PayloadShield.decrypt("base64")` |
+| `PayloadShield("base64")` (function call) | `PayloadShield.crypt("base64")` |
+| `encrypt_response`, `decrypt_request`, `crypto_middleware` | Use the decorators above |
+| No key configuration API | `PayloadShieldEnc.init({...})` |
+
+There is no compatibility shim — update all call sites to the new API.
+
+## Testing
+
+```bash
+# Run the example app
+python examples/example_app.py
+
+# Exercise it with the sample client
+python examples/test_client.py
+
+# Run the test suite
+pytest
+```
+
+## Requirements
+
+- Python 3.7+
+- FastAPI 0.68+
+- Starlette 0.19+
+- cryptography 41+
+
+## Project Layout
+
+- `fastapi_payloadshield/` - Main package
+  - `__init__.py` - Public exports
+  - `config.py` - `PayloadShieldEnc` key configuration
+  - `decorators.py` - `PayloadShield` decorators
+  - `crypto.py` - Handler registry (`register_handler`, `get_handler`)
+  - `EncryptionHandler.py`, `Base64EncryptionHandler.py`,
+    `FernetEncryptionHandler.py`, `AESGCM256EncryptionHandler.py`,
+    `HybridRSAEncryptionHandler.py` - Built-in handlers
+- `examples/` - `example_app.py` demo app and `test_client.py` sample client
+- `tests/` - pytest suite for handlers, config, and decorators
+- `document/` - Additional guides (see [document/](document/))
+
+## License
+
+Apache-2.0 - See [LICENSE](LICENSE) for details.
+

fastapi_payloadshield-1.2.0/README.md

@@ -0,0 +1,225 @@
+# FastAPI Payload Shield
+
+Pluggable FastAPI decorators for encrypting and decrypting request and
+response payloads. Configure your keys once, then annotate any route with
+`@PayloadShield.encrypt`, `@PayloadShield.decrypt`, or `@PayloadShield.crypt`.
+
+> **Breaking change (v3.0.0)**: the old `encrypt_response` /
+> `decrypt_request` / `crypto_middleware` decorators and the old
+> `PayloadShieldEnc("base64")` factory function have been removed. There is
+> no backward-compatible alias — see [Migrating to v3](#migrating-to-v3)
+> below.
+
+## Key Features
+
+- **Pluggable encryption**: base64, Fernet, AES-GCM-256, and Hybrid RSA+AES
+  ship out of the box; register your own with `register_handler(...)`.
+- **One-time key configuration**: `PayloadShieldEnc.init({...})` sets keys
+  globally for all decorators.
+- **Route-agnostic**: no changes needed to your route logic besides adding a
+  decorator.
+- **Async-friendly**: works with FastAPI's async route handlers.
+
+## Installation
+
+```bash
+pip install fastapi_payloadshield
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from fastapi_payloadshield import PayloadShield, PayloadShieldEnc
+
+# Configure encryption keys once, at startup.
+PayloadShieldEnc.init({
+    "Key": "my-symmetric-key",
+})
+
+app = FastAPI()
+
+@app.get("/api/data")
+@PayloadShield.encrypt("base64")
+async def get_data():
+    return {"message": "hello", "data": "world"}
+
+@app.post("/api/process")
+@PayloadShield.decrypt("base64")
+async def process_data(data: dict):
+    return {"received": data, "status": "success"}
+
+@app.post("/api/secure")
+@PayloadShield.crypt("base64")
+async def secure_endpoint(data: dict):
+    return {"processed": data}
+```
+
+## Initialization: `PayloadShieldEnc.init(...)`
+
+Call once before serving requests. Every decorator reads this shared
+configuration at call time.
+
+```python
+PayloadShieldEnc.init({
+    "Key": key,               # symmetric key: fernet, aes-gcm-256
+    "PrivateKey": "string",   # RSA/hybrid private key (file path or PEM content)
+    "PublicKey": "string",    # RSA/hybrid public key (file path or PEM content)
+})
+```
+
+| Field | Used by | Accepts |
+|---|---|---|
+| `Key` | `fernet`, `aes-gcm-256` | Raw key string. `aes-gcm-256` requires the key to resolve to exactly 32 bytes (UTF-8 or base64 encoded). |
+| `PrivateKey` | `rsa-hybrid` (decrypt) | File path to a PEM file, or the raw PEM content. |
+| `PublicKey` | `rsa-hybrid` (encrypt) | File path to a PEM file, or the raw PEM content. |
+
+Only set the fields required by the encryption types you actually use.
+
+## Decorators
+
+All three live on the `PayloadShield` class and take an `encryption_type`
+(default `"base64"`).
+
+### `@PayloadShield.encrypt(encryption_type)`
+
+Encrypts the response payload only.
+
+```python
+@app.get("/api/users")
+@PayloadShield.encrypt("base64")
+async def get_users():
+    return [{"id": 1, "name": "Alice"}]
+
+# Response: {"encrypted": "W3siaWQiOiAxLCAibmFtZSI6ICJBbGljZSJ9XQ=="}
+```
+
+### `@PayloadShield.decrypt(encryption_type)`
+
+Decrypts the request payload only; the route receives the decrypted dict.
+
+```python
+@app.post("/api/login")
+@PayloadShield.decrypt("base64")
+async def login(credentials: dict):
+    return {"status": "success"}
+
+# Expects: {"encrypted": "base64_encoded_json"}
+```
+
+### `@PayloadShield.crypt(encryption_type)`
+
+Decrypts the request and encrypts the response.
+
+```python
+@app.post("/api/secure")
+@PayloadShield.crypt("base64")
+async def secure_endpoint(data: dict):
+    return {"processed": data}
+
+# Expects: {"encrypted": "encrypted_data"}
+# Returns: {"encrypted": "encrypted_data"}
+```
+
+## Built-in Encryption Handlers
+
+| Name | Algorithm | Keys required | Security |
+|---|---|---|---|
+| `base64` | Base64 encoding | none | None — obfuscation only |
+| `fernet` | Fernet (AES-128-CBC + HMAC) | `Key` | Symmetric, authenticated |
+| `aes-gcm-256` | AES-256-GCM | `Key` (32 bytes) | Symmetric, authenticated |
+| `rsa-hybrid` | RSA-OAEP + AES-256-GCM | `PublicKey` (encrypt), `PrivateKey` (decrypt) | Asymmetric/hybrid |
+
+## Custom Handlers
+
+Implement `EncryptionHandler` and register it — every decorator can then
+use it by name.
+
+```python
+from typing import Any, Dict, Optional
+from fastapi_payloadshield import EncryptionHandler, register_handler, PayloadShield
+
+class MyHandler(EncryptionHandler):
+    def encode(self, data: Any, config: Optional[Dict[str, Any]] = None) -> str:
+        ...
+
+    def decode(self, encoded_data: str, config: Optional[Dict[str, Any]] = None) -> Any:
+        ...
+
+register_handler("my-handler", MyHandler())
+
+@app.post("/api/custom")
+@PayloadShield.crypt("my-handler")
+async def custom_endpoint(data: dict):
+    return data
+```
+
+`config` is the dict returned by `PayloadShieldEnc.get_config()` — pull out
+whatever keys your handler needs (`Key`, `PrivateKey`, `PublicKey`).
+
+## How It Works
+
+**Request decryption**: client sends `{"encrypted": "..."}` → decorator
+decodes it with the configured handler → route receives the plain dict.
+
+**Response encryption**: route returns a dict → decorator encodes it with
+the configured handler → client receives `{"encrypted": "..."}`.
+
+## Errors
+
+| Situation | Behavior |
+|---|---|
+| Request decryption fails | `400` response: `{"error": "Failed to decrypt request: ..."}` |
+| Unknown `encryption_type` | `ValueError` raised when the decorator is applied: `Encryption handler '<name>' not found. Available handlers: ...` |
+| Missing required key (e.g. no `Key` set for `fernet`) | `ValueError` raised when encoding/decoding: `... requires 'Key' to be set via PayloadShieldEnc.init(...)` |
+
+## Migrating to v3
+
+| Removed (v2) | Replacement (v3) |
+|---|---|
+| `PayloadShieldEnc("base64")` (decorator factory) | `PayloadShield.encrypt("base64")` |
+| `PayloadShieldDec("base64")` | `PayloadShield.decrypt("base64")` |
+| `PayloadShield("base64")` (function call) | `PayloadShield.crypt("base64")` |
+| `encrypt_response`, `decrypt_request`, `crypto_middleware` | Use the decorators above |
+| No key configuration API | `PayloadShieldEnc.init({...})` |
+
+There is no compatibility shim — update all call sites to the new API.
+
+## Testing
+
+```bash
+# Run the example app
+python examples/example_app.py
+
+# Exercise it with the sample client
+python examples/test_client.py
+
+# Run the test suite
+pytest
+```
+
+## Requirements
+
+- Python 3.7+
+- FastAPI 0.68+
+- Starlette 0.19+
+- cryptography 41+
+
+## Project Layout
+
+- `fastapi_payloadshield/` - Main package
+  - `__init__.py` - Public exports
+  - `config.py` - `PayloadShieldEnc` key configuration
+  - `decorators.py` - `PayloadShield` decorators
+  - `crypto.py` - Handler registry (`register_handler`, `get_handler`)
+  - `EncryptionHandler.py`, `Base64EncryptionHandler.py`,
+    `FernetEncryptionHandler.py`, `AESGCM256EncryptionHandler.py`,
+    `HybridRSAEncryptionHandler.py` - Built-in handlers
+- `examples/` - `example_app.py` demo app and `test_client.py` sample client
+- `tests/` - pytest suite for handlers, config, and decorators
+- `document/` - Additional guides (see [document/](document/))
+
+## License
+
+Apache-2.0 - See [LICENSE](LICENSE) for details.
+

{fastapi_payloadshield-1.0.0 → fastapi_payloadshield-1.2.0}/document/DEVELOPMENT.md

@@ -6,21 +6,31 @@
 FastAPIPS/
 ├── fastapi_payloadshield/           # Main package directory
 │   ├── __init__.py                  # Package initialization & exports
-│   ├── crypto.py                    # Base64 encoding/decoding utilities
-│   └── decorators.py                # FastAPI decorators for encryption/decryption
+│   ├── config.py                    # PayloadShieldEnc key configuration
+│   ├── decorators.py                # PayloadShield.encrypt/decrypt/crypt decorators
+│   ├── crypto.py                    # Handler registry (register_handler/get_handler)
+│   ├── EncryptionHandler.py         # Abstract handler interface
+│   ├── Base64EncryptionHandler.py   # base64 handler
+│   ├── FernetEncryptionHandler.py   # fernet handler
+│   ├── AESGCM256EncryptionHandler.py# aes-gcm-256 handler
+│   └── HybridRSAEncryptionHandler.py# rsa-hybrid handler
 │
 ├── examples/                        # Example implementations
 │   ├── example_app.py               # Full-featured example FastAPI app
 │   └── test_client.py               # Client script to test the API
 │
+├── tests/                           # pytest suite
+│   ├── test_handlers.py             # Handler encode/decode roundtrip tests
+│   ├── test_config.py               # PayloadShieldEnc.init() tests
+│   └── test_decorators.py           # Decorator + FastAPI TestClient tests
+│
 ├── setup.py                         # Classic setup configuration (pip installable)
 ├── pyproject.toml                   # Modern Python project configuration
 ├── requirements.txt                 # Development & runtime dependencies
-├── README.md                        # Comprehensive documentation
-├── QUICKSTART.md                    # Quick start guide
+├── README.md                        # Full API documentation
 ├── MANIFEST.in                      # Files to include in distribution
 ├── .gitignore                       # Git ignore patterns
-└── LICENSE                          # MIT License
+└── LICENSE                          # Apache-2.0 License
 ```
 
 ## Installation for Development
@@ -78,72 +88,29 @@ curl -X POST http://localhost:8000/api/login \
   -d '{"encrypted":"eyJ1c2VybmFtZSI6ICJhZG1pbiIsICJwYXNzd29yZCI6ICJwYXNzd29yZDEyMyJ9"}'
 ```
 
-## Package Components
-
-### 1. `crypto.py` - Utilities
-- `encode_base64(data)` - Encode data to base64
-- `decode_base64(encoded_data)` - Decode base64 to data
-- `encode_response(data)` - Wrap response in encryption format
-- `decode_request(encoded_data)` - Decode request format
-
-### 2. `decorators.py` - Decorators
-- `@encrypt_response` - Encrypts response payload
-- `@decrypt_request` - Decrypts request payload
-- `@crypto_middleware` - Combined encryption/decryption
-
-## Adding New Features
-
-### Add a New Decorator
-1. Edit `fastapi_payloadshield/decorators.py`
-2. Add your decorator function
-3. Export it in `fastapi_payloadshield/__init__.py`
-
-Example:
-```python
-# In decorators.py
-def my_new_decorator(func):
-    @wraps(func)
-    async def wrapper(*args, **kwargs):
-        # Your logic here
-        return await func(*args, **kwargs)
-    return wrapper
-
-# In __init__.py
-from .decorators import my_new_decorator
-__all__ = [..., "my_new_decorator"]
+### Option 3: Run the pytest Suite
+```bash
+pytest
 ```
 
-### Add New Crypto Functions
-1. Edit `fastapi_payloadshield/crypto.py`
-2. Add your function
-3. Export if needed in `__init__.py`
+## Package Components
 
-## Publishing to PyPI
+See [../README.md](../README.md) for the full API reference
+(`PayloadShieldEnc.init`, `PayloadShield.encrypt/decrypt/crypt`, built-in
+handlers, and custom handler registration). This guide only covers
+day-to-day development workflows.
 
-### 1. Update Version
-Edit version in:
-- `setup.py`
-- `pyproject.toml`
-- `fastapi_payloadshield/__init__.py`
+## Adding a New Built-in Handler
 
-### 2. Install Build Tools
-```bash
-pip install build twine
-```
+1. Create `fastapi_payloadshield/MyHandler.py` implementing
+   `EncryptionHandler.encode(data, config)` / `.decode(encoded_data, config)`.
+2. Register it in `fastapi_payloadshield/crypto.py`'s `_HANDLERS` dict.
+3. Export the class from `fastapi_payloadshield/__init__.py`.
+4. Add a roundtrip test in `tests/test_handlers.py`.
 
-### 3. Build Package
-```bash
-python -m build
-```
-
-### 4. Upload to PyPI
-```bash
-# Test PyPI first (optional)
-twine upload --repository testpypi dist/*
+## Publishing to PyPI
 
-# Production PyPI
-twine upload dist/*
-```
+See [PUBLISHING_GUIDE.md](PUBLISHING_GUIDE.md) for the full release process.
 
 ## Code Style
 
@@ -162,27 +129,6 @@ flake8 fastapi_payloadshield examples
 mypy fastapi_payloadshield
 ```
 
-## Creating Tests
-
-Create a `tests/` directory with pytest tests:
-
-```python
-# tests/test_crypto.py
-import pytest
-from fastapi_payloadshield.crypto import encode_base64, decode_base64
-
-def test_encode_decode():
-    data = {"key": "value"}
-    encoded = encode_base64(data)
-    decoded = decode_base64(encoded)
-    assert decoded == data
-```
-
-Run tests:
-```bash
-pytest
-```
-
 ## Contributing
 
 1. Fork the repository
@@ -232,9 +178,11 @@ rm -rf build/ dist/ *.egg-info
 
 - [FastAPI Documentation](https://fastapi.tiangolo.com/)
 - [Python Packaging Guide](https://packaging.python.org/)
-- [Base64 RFC 4648](https://tools.ietf.org/html/rfc4648)
+- [cryptography library](https://cryptography.io/)
 - [Setuptools Documentation](https://setuptools.readthedocs.io/)
 
 ## License
 
-MIT License - See LICENSE file for details
+Apache-2.0 - See [../LICENSE](../LICENSE) for details.
+
+