Django Payload Shield

Pluggable Django decorators for encrypting and decrypting request and response payloads. Configure your keys once, then annotate any view with @PayloadShield.encrypt, @PayloadShield.decrypt, or @PayloadShield.crypt.

Key Features

• Pluggable encryption: base64, Fernet, AES-GCM-256, ChaCha20-Poly1305, Hybrid RSA+AES, ECDH+AES-GCM, ECIES, and HPKE (RFC 9180) ship out of the box; register your own with register_handler(...).
• One-time key configuration: PayloadShieldEnc.init({...}) sets keys globally for all decorators.
• View-agnostic: no changes needed to your view logic besides adding a decorator and reading request.decrypted_data.
• Sync and async friendly: works with both regular def and async def Django views.

Installation

pip install django_payloadshield

Quick Start

from django.urls import path
from django_payloadshield import PayloadShield, PayloadShieldEnc

# Configure encryption keys once, at startup (e.g. in settings.py or AppConfig.ready()).
PayloadShieldEnc.init({
    "Key": "my-symmetric-key",
})

@PayloadShield.encrypt("base64")
def get_data(request):
    return {"message": "hello", "data": "world"}

@PayloadShield.decrypt("base64")
def process_data(request):
    return {"received": request.decrypted_data, "status": "success"}

@PayloadShield.crypt("base64")
def secure_endpoint(request):
    return {"processed": request.decrypted_data}

urlpatterns = [
    path("api/data", get_data),
    path("api/process", process_data),
    path("api/secure", secure_endpoint),
]

Initialization: PayloadShieldEnc.init(...)

Call once before serving requests. Every decorator reads this shared configuration at call time.

PayloadShieldEnc.init({
    "Key": key,               # symmetric key: fernet, aes-gcm-256, chacha20-poly1305
    "PrivateKey": "string",   # RSA/hybrid private key (file path or PEM content)
    "PublicKey": "string",    # RSA/hybrid public key (file path or PEM content)
    "ECPrivateKey": "string", # EC (P-256) private key (file path or PEM content)
    "ECPublicKey": "string",  # EC (P-256) public key (file path or PEM content)
    "HPKEPrivateKey": "string", # X25519 private key (file path or PEM content)
    "HPKEPublicKey": "string",  # X25519 public key (file path or 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.

@PayloadShield.encrypt("base64")
def get_users(request):
    return [{"id": 1, "name": "Alice"}]

# Response: {"encrypted": "W3siaWQiOiAxLCAibmFtZSI6ICJBbGljZSJ9XQ=="}

@PayloadShield.decrypt(encryption_type)

Decrypts the request payload only; the decrypted dict is exposed as request.decrypted_data.

@PayloadShield.decrypt("base64")
def login(request):
    credentials = request.decrypted_data
    return {"status": "success"}

# Expects: {"encrypted": "base64_encoded_json"}

@PayloadShield.crypt(encryption_type)

Decrypts the request and encrypts the response.

@PayloadShield.crypt("base64")
def secure_endpoint(request):
    return {"processed": request.decrypted_data}

# Expects: {"encrypted": "encrypted_data"}
# Returns: {"encrypted": "encrypted_data"}

Views that accept a decrypted body are typically POST-only and should be paired with @csrf_exempt (raw JSON clients rarely send a CSRF token) and @require_POST, applied outside the PayloadShield decorator.

Built-in Encryption Handlers

Custom Handlers

Implement EncryptionHandler and register it — every decorator can then use it by name.

from typing import Any, Dict, Optional
from django_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())

@PayloadShield.crypt("my-handler")
def custom_endpoint(request):
    return request.decrypted_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 → view reads request.decrypted_data.

Response encryption: view returns a dict → decorator encodes it with the configured handler → client receives {"encrypted": "..."}.

Errors

Testing

# Run the example app (also prints Postman-ready request examples)
cd examples
python main.py runserver

# Run the test suite
pytest

Requirements

• Python 3.8+
• Django 3.2+
• cryptography 41+

Project Layout

django_payloadshield/
    __init__.py
    config.py       # PayloadShieldEnc re-export
    crypto.py       # Encryption handlers re-export
    decorators.py   # PayloadShield decorator factories
examples/
    main.py         # Runnable Django app demoing every handler
tests/
    conftest.py
    test_config.py
    test_handlers.py
    test_decorators.py
    test_all_crypts.py