fastapi-payloadshield 1.0.0__tar.gz

fastapi_payloadshield-1.0.0/LICENSE

@@ -0,0 +1,133 @@
+Apache License
+Version 2.0, January 2004
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined in Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity exercising
+   permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or Object
+   form, made available under the License, including but not limited to
+   the software source code, documentation source, and configuration files.
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications thereof
+   or derivative works thereof.
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+   "Licensed Patents" shall mean the patent claims licensable by Licensor
+   that are necessarily infringed by the use or sale of either the Work
+   or Contribution alone or by combination with the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in the License) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work; and
+
+   (d) If the Work includes a "NOTICE" text file, then any
+       Derivative Works that You distribute must include a readable
+       copy of the attribution notices contained within such NOTICE file.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+   or implied, including, without limitation, any warranties or
+   conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or
+   FITNESS FOR A PARTICULAR PURPOSE.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this License.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2024 FastAPI Payload Shield Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

fastapi_payloadshield-1.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include examples *.py
+recursive-include tests *.py
+recursive-include document *.md

fastapi_payloadshield-1.0.0/PKG-INFO

@@ -0,0 +1,364 @@
+Metadata-Version: 2.4
+Name: fastapi_payloadshield
+Version: 1.0.0
+Summary: FastAPI decorators for automatic base64 encryption/decryption of request/response payloads
+Home-page: https://github.com/PayloadShield/FastAPIPS
+Author: Ganesh Kandu
+Author-email: Ganesh Kandu <kanduganesh@gmail.com>
+License: 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: License :: OSI Approved :: Apache Software License
+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
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# FastAPI Payload Shield
+
+Lightweight FastAPI decorators for automatic encryption/decryption of request and response payloads. **Supports pluggable encryption handlers** - easily add new encryption types like AES, Fernet, or custom algorithms!
+
+## 🎯 Key Features
+
+- 🔒 **Flexible Encryption**: Multiple encryption types (base64, AES, Fernet, custom)
+- 🔓 **Automatic Decryption**: Decrypt incoming requests automatically
+- 📝 **JSON-Friendly**: Works seamlessly with JSON requests and responses
+- 🎯 **Route-Agnostic**: No changes needed to your existing route logic
+- ⚡ **Lightweight**: Minimal dependencies and overhead
+- 🚀 **Easy Integration**: Just add decorators to your routes
+- 🧩 **Pluggable**: Create custom encryption handlers easily
+
+## Installation
+
+### From Local Development
+```bash
+cd FastAPIPS
+pip install -e .
+```
+
+### From PyPI (when published)
+```bash
+pip install fastapi_payloadshield
+```
+
+## Quick Start
+
+### Basic Usage with Base64
+
+```python
+from fastapi import FastAPI
+from fastapi_payloadshield import PayloadShieldEnc, PayloadShieldDec, PayloadShield
+
+app = FastAPI()
+
+# Encrypt response only
+@app.get("/api/data")
+@PayloadShieldEnc("base64")
+async def get_data():
+    return {"message": "hello", "data": "world"}
+
+# Decrypt request only
+@app.post("/api/process")
+@PayloadShieldDec("base64")
+async def process_data(data: dict):
+    return {"received": data, "status": "success"}
+
+@app.post("/api/secure")
+@PayloadShield("base64")
+async def secure_endpoint(data: dict):
+    return {"processed": data}
+```
+
+## Decorators
+
+### `@PayloadShieldEnc(encryption_type)`
+
+Encrypts the response payload.
+
+```python
+@app.get("/api/users")
+@PayloadShieldEnc("base64")
+async def get_users():
+    return [{"id": 1, "name": "Alice"}]
+
+# Response: {"encrypted": "W3siaWQiOiAxLCAibmFtZSI6ICJBbGljZSJ9XQ=="}
+```
+
+### `@PayloadShieldDec(encryption_type)`
+
+Decrypts the request payload.
+
+```python
+@app.post("/api/login")
+@PayloadShieldDec("base64")
+async def login(credentials: dict):
+    return {"status": "success"}
+
+# Expects: {"encrypted": "base64_encoded_json"}
+```
+
+### `@PayloadShield(encryption_type)`
+
+Combined encryption and decryption
+
+```python
+@app.post("/api/secure")
+@PayloadShield("base64")
+async def secure_endpoint(data: dict):
+    return {"processed": data}
+
+# Expects: {"encrypted": "encrypted_data"}
+# Returns: {"encrypted": "encrypted_data"}
+```
+
+## Advanced Example: Multiple Encryption Types
+
+```python
+from fastapi import FastAPI
+from fastapi_payloadshield import PayloadShield, register_handler, EncryptionHandler
+from cryptography.fernet import Fernet
+import json
+
+app = FastAPI()
+
+# Create Fernet handler
+class FernetHandler(EncryptionHandler):
+    def __init__(self, key):
+        self.cipher = Fernet(key)
+    
+    def encode(self, data):
+        return self.cipher.encrypt(json.dumps(data).encode()).decode()
+    
+    def decode(self, encoded_data):
+        return json.loads(self.cipher.decrypt(encoded_data.encode()))
+
+# Register
+key = Fernet.generate_key()
+register_handler("fernet", FernetHandler(key))
+
+# Use different encryption for different endpoints
+@app.post("/api/public")
+@PayloadShield("base64")  # Light encryption
+async def public_endpoint(data: dict):
+    return data
+
+@app.post("/api/private")
+@PayloadShield("fernet")  # Strong encryption
+async def private_endpoint(data: dict):
+    return data
+```
+
+## How It Works
+
+### Request Decryption Flow
+1. Client sends: `{"encrypted": "encrypted_data"}`
+2. `@PayloadShieldDec` decorator intercepts
+3. Decrypts using specified handler
+4. Route receives: `{"key": "value"}` (normal dict)
+
+### Response Encryption Flow
+1. Route returns: `{"key": "value"}`
+2. `@PayloadShieldEnc` decorator intercepts
+3. Encrypts using specified handler
+4. Client receives: `{"encrypted": "encrypted_data"}`
+
+## Testing
+
+### Run Example Application
+```bash
+python examples/example_app.py
+```
+
+### Run Test Client
+```bash
+python examples/test_client.py
+```
+
+### Manual Test with cURL
+
+```bash
+# Encrypt test data
+echo '{"username":"admin"}' | base64
+# eyJ1c2VybmFtZSI6ImFkbWluIn0=
+
+# Send encrypted request
+curl -X POST http://localhost:8000/api/login \
+  -H "Content-Type: application/json" \
+  -d '{"encrypted":"eyJ1c2VybmFtZSI6ImFkbWluIn0="}'
+```
+
+### Testing with Python
+```python
+import requests
+import json
+import base64
+
+# Encode request
+data = {"username": "admin", "password": "secret"}
+json_str = json.dumps(data)
+encrypted = base64.b64encode(json_str.encode()).decode()
+
+# Send request
+response = requests.post(
+    "http://localhost:8000/api/login",
+    json={"encrypted": encrypted}
+)
+
+# Decode response
+encrypted_response = response.json()["encrypted"]
+decrypted = json.loads(base64.b64decode(encrypted_response).decode())
+print(decrypted)
+# {'status': 'success', 'token': 'abc123'}
+```
+
+## Creating Custom Encryption Handlers
+
+See [CUSTOM_HANDLERS.md](CUSTOM_HANDLERS.md) for detailed guide on:
+
+- Creating custom handlers
+- Fernet encryption example
+- AES encryption example
+- Best practices
+- Performance tips
+- Security considerations
+
+## Backward Compatibility
+
+Old decorator names still work:
+
+```python
+from fastapi_payloadshield import encrypt_response, decrypt_request, crypto_middleware
+
+# These are equivalent to:
+# PayloadShieldEnc("base64")
+# PayloadShieldDec("base64")
+# PayloadShield("base64")
+
+@app.get("/api/data")
+@encrypt_response
+async def get_data():
+    return {"data": "value"}
+```
+
+## API Reference
+
+### Decorators
+
+| Decorator | Purpose |
+|-----------|---------|
+| `PayloadShieldEnc(type)` | Encrypt response |
+| `PayloadShieldDec(type)` | Decrypt request |
+| `PayloadShield(type)` | Both encrypt & decrypt |
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `register_handler(name, handler)` | Register custom encryption handler |
+| `get_handler(name)` | Get handler by name |
+| `EncryptionHandler` | Base class for handlers |
+
+### Built-in Handlers
+
+| Handler | Type | Security | Use Case |
+|---------|------|----------|----------|
+| `base64` | Encoding | None | Obfuscation, development |
+
+## Error Handling
+
+The decorators include built-in error handling:
+
+```python
+# Invalid encrypted data
+# Response: {"error": "Failed to decrypt request: ..."}
+
+# Missing encryption handler  
+# Response: ValueError: Encryption handler 'xyz' not found. Available: base64, fernet
+```
+
+## Performance Considerations
+
+- **Caching**: Handler instances are cached
+- **Compression**: Consider compressing before encryption for large payloads
+- **Async**: All operations are async-friendly
+
+## Requirements
+
+- Python 3.7+
+- FastAPI 0.68+
+- Starlette 0.19+
+
+## Files Included
+
+- `fastapi_payloadshield/` - Main package
+  - `__init__.py` - Exports decorators and handlers
+  - `crypto.py` - Encryption handlers
+  - `decorators.py` - FastAPI decorators
+- `examples/` - Working examples
+  - `example_app.py` - Full-featured demo
+  - `test_client.py` - Test/client script
+- `README.md` - This file
+- `QUICKSTART.md` - Quick start guide
+- `CUSTOM_HANDLERS.md` - Creating custom handlers
+- `DEVELOPMENT.md` - Development guide
+
+## License
+
+Apache-2.0 - See LICENSE file for details
+
+## Contributing
+
+Contributions welcome! Areas for contribution:
+
+1. New encryption handlers (AES, Fernet, etc.)
+2. Performance optimizations
+3. Documentation improvements
+4. Test coverage
+5. Examples
+
+## Support
+
+- 📖 Full guide: [README.md](README.md)
+- ⚡ Quick start: [QUICKSTART.md](QUICKSTART.md)
+- 🧩 Custom handlers: [CUSTOM_HANDLERS.md](CUSTOM_HANDLERS.md)
+- 🛠️ Development: [DEVELOPMENT.md](DEVELOPMENT.md)
+
+---
+
+**Happy encrypting!** 🔒
+
+## Why Payload Shield?
+
+This package was designed with extensibility in mind. Unlike static encryption libraries, Payload Shield lets you:
+
+- Mix and match encryption types in the same app
+- Add new encryption types without touching core code
+- Keep route logic clean and simple
+- Support multiple security levels
+
+Perfect for:
+- Building multi-tier security APIs
+- Migrating from one encryption to another
+- Testing different encryption strategies
+- Production systems requiring flexible crypto