persistence-kit 3.10.1__tar.gz → 3.12.0__tar.gz

{persistence_kit-3.10.1 → persistence_kit-3.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: persistence-kit
-Version: 3.10.1
+Version: 3.12.0
 Summary: Reusable persistence and repository toolkit
 License: MIT
 License-File: LICENSE
@@ -21,6 +21,7 @@ Classifier: Typing :: Typed
 Provides-Extra: all
 Provides-Extra: api
 Provides-Extra: dynamodb
+Provides-Extra: encrypted
 Provides-Extra: restclient
 Provides-Extra: security
 Provides-Extra: security-cognito
@@ -29,7 +30,8 @@ Provides-Extra: storage-s3
 Provides-Extra: testing
 Requires-Dist: asyncpg (>=0.30.0,<1.0.0)
 Requires-Dist: boto3 (>=1.35.0,<2.0.0) ; extra == "storage-s3" or extra == "security-cognito" or extra == "dynamodb" or extra == "all"
-Requires-Dist: fastapi (>=0.115.0,<1.0.0) ; extra == "api" or extra == "storage-routes" or extra == "security" or extra == "security-cognito" or extra == "testing" or extra == "all"
+Requires-Dist: cryptography (>=42.0.0,<43.0.0) ; extra == "encrypted" or extra == "testing" or extra == "all"
+Requires-Dist: fastapi (>=0.115.0,<1.0.0) ; extra == "api" or extra == "storage-routes" or extra == "security" or extra == "security-cognito" or extra == "encrypted" or extra == "testing" or extra == "all"
 Requires-Dist: httpx (>=0.28.0,<1.0.0) ; extra == "restclient" or extra == "testing" or extra == "all"
 Requires-Dist: motor (>=3.7.1,<4.0.0)
 Requires-Dist: pydantic-settings (>=2.3.0,<3.0.0)
@@ -149,7 +151,8 @@ pip install "persistence-kit[api,security,restclient]"
 | `storage-routes` | FastAPI route to serve local exports | fastapi, python-multipart |
 | `dynamodb` | DynamoDB repository backend | boto3 |
 | `restclient` | The REST client and its cache | httpx |
-| `testing` | Everything the test suite needs | fastapi, pyjwt, httpx, python-multipart |
+| `encrypted` | Encrypted request and response payloads | fastapi, cryptography |
+| `testing` | Everything the test suite needs | fastapi, pyjwt, httpx, python-multipart, cryptography |
 | `all` | Every optional capability | all of the above |
 
 Importing `persistence_kit` never loads an optional dependency by itself. Ask for
@@ -165,11 +168,11 @@ add, not an obscure `ImportError`.
 | `repository_factory/` | The entity registry, the factory, and the view repository that populates relations |
 | `settings/` | `RepoSettings` and `PersistenceKitSettings`, plus shared enums and parsers |
 | `storage/` | Object storage: local directory or S3, with presigned URLs |
-| `security/` | Identity providers and JWT verifiers, memory or Cognito |
+| `security/` | Identity providers and JWT verifiers, memory or Cognito, and the encrypted envelope format |
 | `restclient/` | HTTP client with pluggable auth, endpoint resolution, retries and DTO decoding |
 | `cache/` | Key-value cache with TTL: memory, Mongo or DynamoDB |
 | `resilience/` | Circuit breaker, shared by anything that calls out |
-| `api/` | Reusable FastAPI pieces: error handlers, pagination, rate limiting |
+| `api/` | Reusable FastAPI pieces: error handlers, pagination, rate limiting, encrypted routes |
 | `bootstrap/` | Startup helpers, configuration registry, seed orchestration |
 | `utils/` | Small transversal helpers such as upserts |
 
@@ -231,6 +234,65 @@ application. The kit only answers "who is this".
 
 Needs `[security]`, or `[security-cognito]` for Cognito.
 
+## Encrypted payloads
+
+For data that should not be readable between the browser and your handler, not
+even to a proxy that terminates TLS.
+
+```python
+from fastapi import APIRouter, FastAPI
+
+from persistence_kit import (
+    EncryptedResponseMiddleware,
+    build_encrypted_route,
+    encrypted,
+)
+
+router = APIRouter(route_class=build_encrypted_route(get_settings))
+
+
+@router.post("/login", openapi_extra=encrypted(fields=["password"], response_fields=["token"]))
+async def login(payload: LoginRequest) -> LoginResponse:
+    ...
+
+
+app = FastAPI()
+app.add_middleware(EncryptedResponseMiddleware)
+app.include_router(router)
+```
+
+The client generates one AES-256-GCM key per request, wraps it with the server's
+public key, and sends it inside the envelope. The route unwraps it and opens the
+payload before your handler runs; the middleware encrypts whatever comes back with
+the same key, including the errors your own `exception_handler` builds. Your
+handler never sees an envelope, and both pieces are required.
+
+Two modes. `encrypted()` encrypts the whole body and the whole response.
+`encrypted(fields=[...])` encrypts named fields only, so the rest of the payload
+stays readable; paths may be nested and may cross lists, as in `items[].price`.
+Those paths are validated when the route is mounted — against your Pydantic body
+when there is one — so a typo fails at startup rather than quietly leaving the
+field unencrypted.
+
+By default the private key is generated in memory at startup, so encrypted routes
+work with no configuration. Set `ENCRYPTED_TYPE=local` to load a fixed base64 PEM
+from `ENCRYPTED_PRIVATE_KEY`, or `ENCRYPTED_TYPE=kms` to keep it inside AWS
+KMS. Clients fetch the matching public key from your own endpoint, built on
+`public_key_der_b64(provider)`.
+
+Outside the local stage the kit logs a warning when `ENCRYPTED_TYPE=memory` or
+`CACHE_BACKEND=memory`: both keep per-process state that several replicas do not
+share. It warns and starts anyway.
+
+Envelopes carry a timestamp, expire after sixty seconds, and each nonce is
+accepted once, so a captured request cannot be replayed. Anything malformed,
+expired, replayed or tampered with comes back as a 400.
+
+In `local` stage a plain body is allowed through, so you can call your API from
+Swagger while developing.
+
+Needs `[encrypted]`.
+
 ## REST client and cache
 
 For calling somebody else's HTTP API without writing the same client again.
@@ -310,6 +372,9 @@ The factories read that object: `get_identity_provider`, `get_token_verifier`,
 | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DB` | Postgres connection |
 | `POSTGRES_SSL` | Set when the server requires TLS |
 | `DYNAMODB_REGION`, `DYNAMODB_TABLE_PREFIX` | DynamoDB connection |
+| `ENCRYPTED_PRIVATE_KEY` | Base64 PEM of the RSA private key that unwraps encrypted payloads |
+| `ENCRYPTED_TYPE` | `memory` (default, key generated at startup), `local`, or `kms` for AWS KMS |
+| `KMS_KEY_ID` | The KMS key that unwraps the AES key, required by `kms` |
 
 ## Wiring it into an application
 
@@ -433,7 +498,7 @@ poetry install --with dev --all-extras
 poetry run pytest -q
 ```
 
-Current baseline: **434 tests passing** (version 3.9.1). Async tests use
+Current baseline: **555 tests passing** (version 3.12.0). Async tests use
 `pytest-asyncio` in strict mode, so each one carries `@pytest.mark.asyncio`.
 
 `tests/test_capabilities.py` guards the lazy-import promise: it fails if merely
@@ -471,6 +536,7 @@ every iteration.
 
 - [`docs/repositories_and_relations.md`](docs/repositories_and_relations.md): relations, pivots, and how the view repository populates them.
 - [`docs/restclient_and_cache.md`](docs/restclient_and_cache.md): the REST client, its auth strategies, and the cache.
+- [`docs/encrypted_payloads.md`](docs/encrypted_payloads.md): the envelope format, the key providers, and what the client has to do.
 
 Author: Andres Felipe Serrano Barrios · [github.com/AndresFSerrano/persistence-kit](https://github.com/AndresFSerrano/persistence-kit)
 

{persistence_kit-3.10.1 → persistence_kit-3.12.0}/README.md

@@ -105,7 +105,8 @@ pip install "persistence-kit[api,security,restclient]"
 | `storage-routes` | FastAPI route to serve local exports | fastapi, python-multipart |
 | `dynamodb` | DynamoDB repository backend | boto3 |
 | `restclient` | The REST client and its cache | httpx |
-| `testing` | Everything the test suite needs | fastapi, pyjwt, httpx, python-multipart |
+| `encrypted` | Encrypted request and response payloads | fastapi, cryptography |
+| `testing` | Everything the test suite needs | fastapi, pyjwt, httpx, python-multipart, cryptography |
 | `all` | Every optional capability | all of the above |
 
 Importing `persistence_kit` never loads an optional dependency by itself. Ask for
@@ -121,11 +122,11 @@ add, not an obscure `ImportError`.
 | `repository_factory/` | The entity registry, the factory, and the view repository that populates relations |
 | `settings/` | `RepoSettings` and `PersistenceKitSettings`, plus shared enums and parsers |
 | `storage/` | Object storage: local directory or S3, with presigned URLs |
-| `security/` | Identity providers and JWT verifiers, memory or Cognito |
+| `security/` | Identity providers and JWT verifiers, memory or Cognito, and the encrypted envelope format |
 | `restclient/` | HTTP client with pluggable auth, endpoint resolution, retries and DTO decoding |
 | `cache/` | Key-value cache with TTL: memory, Mongo or DynamoDB |
 | `resilience/` | Circuit breaker, shared by anything that calls out |
-| `api/` | Reusable FastAPI pieces: error handlers, pagination, rate limiting |
+| `api/` | Reusable FastAPI pieces: error handlers, pagination, rate limiting, encrypted routes |
 | `bootstrap/` | Startup helpers, configuration registry, seed orchestration |
 | `utils/` | Small transversal helpers such as upserts |
 
@@ -187,6 +188,65 @@ application. The kit only answers "who is this".
 
 Needs `[security]`, or `[security-cognito]` for Cognito.
 
+## Encrypted payloads
+
+For data that should not be readable between the browser and your handler, not
+even to a proxy that terminates TLS.
+
+```python
+from fastapi import APIRouter, FastAPI
+
+from persistence_kit import (
+    EncryptedResponseMiddleware,
+    build_encrypted_route,
+    encrypted,
+)
+
+router = APIRouter(route_class=build_encrypted_route(get_settings))
+
+
+@router.post("/login", openapi_extra=encrypted(fields=["password"], response_fields=["token"]))
+async def login(payload: LoginRequest) -> LoginResponse:
+    ...
+
+
+app = FastAPI()
+app.add_middleware(EncryptedResponseMiddleware)
+app.include_router(router)
+```
+
+The client generates one AES-256-GCM key per request, wraps it with the server's
+public key, and sends it inside the envelope. The route unwraps it and opens the
+payload before your handler runs; the middleware encrypts whatever comes back with
+the same key, including the errors your own `exception_handler` builds. Your
+handler never sees an envelope, and both pieces are required.
+
+Two modes. `encrypted()` encrypts the whole body and the whole response.
+`encrypted(fields=[...])` encrypts named fields only, so the rest of the payload
+stays readable; paths may be nested and may cross lists, as in `items[].price`.
+Those paths are validated when the route is mounted — against your Pydantic body
+when there is one — so a typo fails at startup rather than quietly leaving the
+field unencrypted.
+
+By default the private key is generated in memory at startup, so encrypted routes
+work with no configuration. Set `ENCRYPTED_TYPE=local` to load a fixed base64 PEM
+from `ENCRYPTED_PRIVATE_KEY`, or `ENCRYPTED_TYPE=kms` to keep it inside AWS
+KMS. Clients fetch the matching public key from your own endpoint, built on
+`public_key_der_b64(provider)`.
+
+Outside the local stage the kit logs a warning when `ENCRYPTED_TYPE=memory` or
+`CACHE_BACKEND=memory`: both keep per-process state that several replicas do not
+share. It warns and starts anyway.
+
+Envelopes carry a timestamp, expire after sixty seconds, and each nonce is
+accepted once, so a captured request cannot be replayed. Anything malformed,
+expired, replayed or tampered with comes back as a 400.
+
+In `local` stage a plain body is allowed through, so you can call your API from
+Swagger while developing.
+
+Needs `[encrypted]`.
+
 ## REST client and cache
 
 For calling somebody else's HTTP API without writing the same client again.
@@ -266,6 +326,9 @@ The factories read that object: `get_identity_provider`, `get_token_verifier`,
 | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DB` | Postgres connection |
 | `POSTGRES_SSL` | Set when the server requires TLS |
 | `DYNAMODB_REGION`, `DYNAMODB_TABLE_PREFIX` | DynamoDB connection |
+| `ENCRYPTED_PRIVATE_KEY` | Base64 PEM of the RSA private key that unwraps encrypted payloads |
+| `ENCRYPTED_TYPE` | `memory` (default, key generated at startup), `local`, or `kms` for AWS KMS |
+| `KMS_KEY_ID` | The KMS key that unwraps the AES key, required by `kms` |
 
 ## Wiring it into an application
 
@@ -389,7 +452,7 @@ poetry install --with dev --all-extras
 poetry run pytest -q
 ```
 
-Current baseline: **434 tests passing** (version 3.9.1). Async tests use
+Current baseline: **555 tests passing** (version 3.12.0). Async tests use
 `pytest-asyncio` in strict mode, so each one carries `@pytest.mark.asyncio`.
 
 `tests/test_capabilities.py` guards the lazy-import promise: it fails if merely
@@ -427,5 +490,6 @@ every iteration.
 
 - [`docs/repositories_and_relations.md`](docs/repositories_and_relations.md): relations, pivots, and how the view repository populates them.
 - [`docs/restclient_and_cache.md`](docs/restclient_and_cache.md): the REST client, its auth strategies, and the cache.
+- [`docs/encrypted_payloads.md`](docs/encrypted_payloads.md): the envelope format, the key providers, and what the client has to do.
 
 Author: Andres Felipe Serrano Barrios · [github.com/AndresFSerrano/persistence-kit](https://github.com/AndresFSerrano/persistence-kit)

{persistence_kit-3.10.1 → persistence_kit-3.12.0}/persistence_kit/__init__.py

@@ -14,6 +14,7 @@ from .settings import (
     DeploymentStage,
     ExportStorageProvider,
     MediaStorageProvider,
+    EncryptedType,
     PersistenceKitSettings,
 )
 from .settings.constants import Database
@@ -96,6 +97,51 @@ _OPTIONAL_EXPORTS = {
         "get_token_verifier",
         "security",
     ),
+    "KeyProvider": ("persistence_kit.security.ports", "KeyProvider", "security"),
+    "get_key_provider": ("persistence_kit.security.factory", "get_key_provider", "security"),
+    "public_key_der_b64": (
+        "persistence_kit.security.ports",
+        "public_key_der_b64",
+        "encrypted",
+    ),
+    "LocalKeyProvider": (
+        "persistence_kit.security.providers.encryption_provider",
+        "LocalKeyProvider",
+        "encrypted",
+    ),
+    "MemoryKeyProvider": (
+        "persistence_kit.security.providers.encryption_provider",
+        "MemoryKeyProvider",
+        "encrypted",
+    ),
+    "KmsKeyProvider": (
+        "persistence_kit.security.providers.encryption_provider",
+        "KmsKeyProvider",
+        "encrypted",
+    ),
+    "EncryptedPayloadError": (
+        "persistence_kit.security.encrypted.errors",
+        "EncryptedPayloadError",
+        "encrypted",
+    ),
+    "encrypted": ("persistence_kit.api.encrypted_routes", "encrypted", "encrypted"),
+    "build_encrypted_route": (
+        "persistence_kit.api.encrypted_routes",
+        "build_encrypted_route",
+        "encrypted",
+    ),
+    "EncryptedResponseMiddleware": (
+        "persistence_kit.api.encrypted_middleware",
+        "EncryptedResponseMiddleware",
+        "encrypted",
+    ),
+    "declare_key_header": (
+        "persistence_kit.api.encrypted_routes",
+        "declare_key_header",
+        "encrypted",
+    ),
+    "ENCRYPTED_FLAG": ("persistence_kit.api.encrypted_routes", "ENCRYPTED_FLAG", "encrypted"),
+    "KEY_HEADER": ("persistence_kit.api.encrypted_routes", "KEY_HEADER", "encrypted"),
     "RegistrationResult": (
         "persistence_kit.security.registration",
         "RegistrationResult",
@@ -286,6 +332,7 @@ __all__ = [
     "AuthProvider",
     "ExportStorageProvider",
     "MediaStorageProvider",
+    "EncryptedType",
     "DeploymentStage",
     "LOCAL_DEFAULT_JOB_SERVICE_API_KEY",
     "DEFAULT_MEMORY_JWT_SECRET",

persistence_kit-3.12.0/persistence_kit/api/__init__.py

@@ -0,0 +1,55 @@
+from .common import ApiError, pagination_params
+from .error_handlers import handle_repository_errors, handle_service_errors
+from .exceptions import (
+    BaseAPIException,
+    BusinessRuleException,
+    DatabaseException,
+    NotFoundException,
+    ValidationException,
+)
+from .rate_limit import InMemoryRateLimiter, build_auth_rate_limit_dependency
+from .route_loader import build_api_router
+
+_LAZY = {
+    "KEY_HEADER": ("persistence_kit.api.encrypted_routes", "KEY_HEADER"),
+    "ENCRYPTED_FLAG": ("persistence_kit.api.encrypted_routes", "ENCRYPTED_FLAG"),
+    "build_encrypted_route": ("persistence_kit.api.encrypted_routes", "build_encrypted_route"),
+    "declare_key_header": ("persistence_kit.api.encrypted_routes", "declare_key_header"),
+    "encrypted": ("persistence_kit.api.encrypted_routes", "encrypted"),
+    "EncryptedResponseMiddleware": (
+        "persistence_kit.api.encrypted_middleware",
+        "EncryptedResponseMiddleware",
+    ),
+}
+
+__all__ = [
+    "ApiError",
+    "pagination_params",
+    "BaseAPIException",
+    "NotFoundException",
+    "ValidationException",
+    "BusinessRuleException",
+    "DatabaseException",
+    "handle_service_errors",
+    "handle_repository_errors",
+    "build_api_router",
+    "InMemoryRateLimiter",
+    "build_auth_rate_limit_dependency",
+    "build_encrypted_route",
+    "EncryptedResponseMiddleware",
+    "encrypted",
+    "declare_key_header",
+    "ENCRYPTED_FLAG",
+    "KEY_HEADER",
+]
+
+
+def __getattr__(name: str):
+    if name in _LAZY:
+        from importlib import import_module
+
+        module_name, attr = _LAZY[name]
+        value = getattr(import_module(module_name), attr)
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

persistence_kit-3.12.0/persistence_kit/api/encrypted_middleware.py

@@ -0,0 +1,65 @@
+import json
+from collections.abc import Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+from fastapi.responses import JSONResponse
+
+from persistence_kit.api.encrypted_routes import (
+    KEY_STATE,
+    RESPONSE_FIELDS_STATE,
+    locate_all,
+)
+from persistence_kit.security.encrypted.envelope import encrypt
+from persistence_kit.security.encrypted.errors import EncryptedPayloadError
+
+
+def _encrypt_fields(payload: dict | list, fields: list[str], data_key: bytes) -> dict | list:
+    if isinstance(payload, list):
+        return [_encrypt_fields(item, fields, data_key) for item in payload]
+    if not isinstance(payload, dict):
+        raise EncryptedPayloadError("La respuesta debe ser un objeto o una lista de objetos")
+    for field in fields:
+        for container, key in locate_all(payload, field):
+            if key in container:
+                container[key] = encrypt(json.dumps(container[key]).encode(), data_key)
+    return payload
+
+
+def _encrypted_response(payload, source: Response) -> JSONResponse:
+    response = JSONResponse(payload, status_code=source.status_code)
+    response.raw_headers += [
+        (name, value)
+        for name, value in source.raw_headers
+        if name not in (b"content-length", b"content-type")
+    ]
+    return response
+
+
+class EncryptedResponseMiddleware(BaseHTTPMiddleware):
+    """Encrypts the response of routes marked with ``encrypted()``.
+
+    Runs outside the ``ExceptionMiddleware``, so it also covers the responses
+    built by the app's own exception handlers. The route only leaves the key on
+    ``request.state``.
+    """
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        response = await call_next(request)
+        data_key = getattr(request.state, KEY_STATE, None)
+        if data_key is None:
+            return response
+
+        body = b"".join([chunk async for chunk in response.body_iterator])
+        if not body:
+            empty = Response(status_code=response.status_code)
+            empty.raw_headers = list(response.raw_headers)
+            return empty
+
+        response_fields = getattr(request.state, RESPONSE_FIELDS_STATE, None)
+        if response_fields:
+            payload = _encrypt_fields(json.loads(body), response_fields, data_key)
+        else:
+            payload = encrypt(body, data_key)
+        return _encrypted_response(payload, response)