persistence-kit 3.11.0__tar.gz → 3.13.0__tar.gz

{persistence_kit-3.11.0 → persistence_kit-3.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: persistence-kit
-Version: 3.11.0
+Version: 3.13.0
 Summary: Reusable persistence and repository toolkit
 License: MIT
 License-File: LICENSE
@@ -21,6 +21,8 @@ Classifier: Typing :: Typed
 Provides-Extra: all
 Provides-Extra: api
 Provides-Extra: dynamodb
+Provides-Extra: encrypted
+Provides-Extra: mail
 Provides-Extra: restclient
 Provides-Extra: security
 Provides-Extra: security-cognito
@@ -29,8 +31,10 @@ 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: jinja2 (>=3.1.4,<4.0.0) ; extra == "mail" 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)
 Requires-Dist: pyjwt[crypto] (>=2.10.1,<3.0.0) ; extra == "security" or extra == "security-cognito" or extra == "testing" or extra == "all"
@@ -149,7 +153,9 @@ 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 |
+| `mail` | Mail templates rendered with Jinja2 (sending itself needs no extra) | jinja2 |
+| `testing` | Everything the test suite needs | fastapi, pyjwt, httpx, python-multipart, cryptography, jinja2 |
 | `all` | Every optional capability | all of the above |
 
 Importing `persistence_kit` never loads an optional dependency by itself. Ask for
@@ -165,11 +171,12 @@ 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 |
+| `mail/` | Outbound mail through an SMTP relay, with templates that live in the app |
 | `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 +238,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.
@@ -271,6 +337,69 @@ Both are covered in depth in [`docs/restclient_and_cache.md`](docs/restclient_an
 
 Needs `[restclient]`.
 
+## Mail
+
+Sending mail from an application without it knowing which relay carries it.
+The kit ships the machinery and no templates: the words belong to the app that
+sends them.
+
+```python
+from persistence_kit.mail import MailMessage, build_mailer
+
+mailer = build_mailer("app/templates/mail")
+
+message = mailer.compose(
+    "user_roles_changed",
+    to="ana@udea.edu.co",
+    cc=["coordinacion@udea.edu.co"],
+    bcc="auditoria@udea.edu.co",
+    context={"name": "Ana", "roles": ["Préstamos", "Reportes"]},
+)
+mailer.dispatch(message)
+```
+
+A template is up to three files in the app's directory: `user_roles_changed.subject.txt`
+(required), and `user_roles_changed.html` or `user_roles_changed.txt` (at least one).
+They are Jinja2, so a layout can be shared with `{% extends %}`. HTML is autoescaped,
+and a variable missing from the context fails instead of rendering blank.
+
+`to`, `cc`, `bcc` and `reply_to` take a string, a `MailAddress` or a list of them.
+Blind copies travel in the SMTP envelope only and never appear in the headers.
+Attachments go in `attachments` as `MailAttachment(filename, content, content_type)`.
+
+`compose` raises on a broken template, so a test that composes every template
+catches it. `dispatch` delivers in the background: if the relay fails, the error
+is logged and the request that triggered the mail carries on. Use `await
+mailer.send(message)` when the caller has to know, and `await
+mailer.wait_for_pending()` in tests or at shutdown.
+
+Images are embedded, not linked: `<img src="cid:logo.png">` in a template attaches
+`images/logo.png` from the same directory as an inline part, so it shows even where
+remote images are blocked. `compose` adds it on its own; a missing file or one that
+is not an image fails like a missing variable. `MailAttachment(..., content_id=...)`
+does the same for images the caller builds.
+
+A template can carry a fourth file, `user_roles_changed.sample.json`, with an
+example context. `MailTemplates.names()` lists the templates and
+`sample_context(name)` reads that file, so one parametrized test covers them all.
+The same sample drives the preview, which renders without sending:
+
+```bash
+python -m persistence_kit.mail.preview app/templates/mail user_roles_changed
+```
+
+It writes the `.html` and the `.txt` to a temporary folder, prints the subject
+and opens the HTML in the browser. Without names it renders every template;
+`--output` changes the folder and `--no-open` skips the browser.
+
+The sender is chosen by `MAIL_BACKEND`. `memory` keeps messages in
+`MemoryMailSender.sent`, for tests and for local runs where no relay accepts you.
+`smtp` delivers through `SmtpMailSender`, which upgrades with STARTTLS and logs in
+only if `MAIL_SMTP_USERNAME` is set, so a relay that authorizes by IP works as is.
+
+Needs `[mail]` for templates. `MailMessage` and the senders use only the standard
+library.
+
 ## Resilience
 
 `CircuitBreaker` is domain-agnostic and shared by anything that calls out: after
@@ -295,7 +424,7 @@ class Settings(PersistenceKitSettings):
 ```
 
 The factories read that object: `get_identity_provider`, `get_token_verifier`,
-`get_export_storage`, `get_cache`.
+`get_export_storage`, `get_cache`, `get_mail_sender`.
 
 ### Environment variables
 
@@ -310,6 +439,15 @@ 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` |
+| `MAIL_BACKEND` | `memory` (default) or `smtp` |
+| `MAIL_FROM_ADDRESS`, `MAIL_FROM_NAME` | Default sender. The address is required by `smtp` |
+| `MAIL_SMTP_HOST`, `MAIL_SMTP_PORT` | The relay. Port defaults to `587` |
+| `MAIL_SMTP_STARTTLS` | Upgrade the connection with STARTTLS. Defaults to `true` |
+| `MAIL_SMTP_USERNAME`, `MAIL_SMTP_PASSWORD` | Only for relays that require a login |
+| `MAIL_SMTP_TIMEOUT_SECONDS` | Connection and command timeout. Defaults to `30` |
 
 ## Wiring it into an application
 
@@ -433,11 +571,11 @@ poetry install --with dev --all-extras
 poetry run pytest -q
 ```
 
-Current baseline: **434 tests passing** (version 3.9.1). Async tests use
+Current baseline: **621 tests passing** (version 3.13.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
-importing `persistence_kit` drags in fastapi, pyjwt or boto3.
+importing `persistence_kit` drags in fastapi, pyjwt, boto3 or jinja2.
 
 ## Releasing
 
@@ -471,6 +609,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.11.0 → persistence_kit-3.13.0}/README.md

@@ -105,7 +105,9 @@ 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 |
+| `mail` | Mail templates rendered with Jinja2 (sending itself needs no extra) | jinja2 |
+| `testing` | Everything the test suite needs | fastapi, pyjwt, httpx, python-multipart, cryptography, jinja2 |
 | `all` | Every optional capability | all of the above |
 
 Importing `persistence_kit` never loads an optional dependency by itself. Ask for
@@ -121,11 +123,12 @@ 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 |
+| `mail/` | Outbound mail through an SMTP relay, with templates that live in the app |
 | `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 +190,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.
@@ -227,6 +289,69 @@ Both are covered in depth in [`docs/restclient_and_cache.md`](docs/restclient_an
 
 Needs `[restclient]`.
 
+## Mail
+
+Sending mail from an application without it knowing which relay carries it.
+The kit ships the machinery and no templates: the words belong to the app that
+sends them.
+
+```python
+from persistence_kit.mail import MailMessage, build_mailer
+
+mailer = build_mailer("app/templates/mail")
+
+message = mailer.compose(
+    "user_roles_changed",
+    to="ana@udea.edu.co",
+    cc=["coordinacion@udea.edu.co"],
+    bcc="auditoria@udea.edu.co",
+    context={"name": "Ana", "roles": ["Préstamos", "Reportes"]},
+)
+mailer.dispatch(message)
+```
+
+A template is up to three files in the app's directory: `user_roles_changed.subject.txt`
+(required), and `user_roles_changed.html` or `user_roles_changed.txt` (at least one).
+They are Jinja2, so a layout can be shared with `{% extends %}`. HTML is autoescaped,
+and a variable missing from the context fails instead of rendering blank.
+
+`to`, `cc`, `bcc` and `reply_to` take a string, a `MailAddress` or a list of them.
+Blind copies travel in the SMTP envelope only and never appear in the headers.
+Attachments go in `attachments` as `MailAttachment(filename, content, content_type)`.
+
+`compose` raises on a broken template, so a test that composes every template
+catches it. `dispatch` delivers in the background: if the relay fails, the error
+is logged and the request that triggered the mail carries on. Use `await
+mailer.send(message)` when the caller has to know, and `await
+mailer.wait_for_pending()` in tests or at shutdown.
+
+Images are embedded, not linked: `<img src="cid:logo.png">` in a template attaches
+`images/logo.png` from the same directory as an inline part, so it shows even where
+remote images are blocked. `compose` adds it on its own; a missing file or one that
+is not an image fails like a missing variable. `MailAttachment(..., content_id=...)`
+does the same for images the caller builds.
+
+A template can carry a fourth file, `user_roles_changed.sample.json`, with an
+example context. `MailTemplates.names()` lists the templates and
+`sample_context(name)` reads that file, so one parametrized test covers them all.
+The same sample drives the preview, which renders without sending:
+
+```bash
+python -m persistence_kit.mail.preview app/templates/mail user_roles_changed
+```
+
+It writes the `.html` and the `.txt` to a temporary folder, prints the subject
+and opens the HTML in the browser. Without names it renders every template;
+`--output` changes the folder and `--no-open` skips the browser.
+
+The sender is chosen by `MAIL_BACKEND`. `memory` keeps messages in
+`MemoryMailSender.sent`, for tests and for local runs where no relay accepts you.
+`smtp` delivers through `SmtpMailSender`, which upgrades with STARTTLS and logs in
+only if `MAIL_SMTP_USERNAME` is set, so a relay that authorizes by IP works as is.
+
+Needs `[mail]` for templates. `MailMessage` and the senders use only the standard
+library.
+
 ## Resilience
 
 `CircuitBreaker` is domain-agnostic and shared by anything that calls out: after
@@ -251,7 +376,7 @@ class Settings(PersistenceKitSettings):
 ```
 
 The factories read that object: `get_identity_provider`, `get_token_verifier`,
-`get_export_storage`, `get_cache`.
+`get_export_storage`, `get_cache`, `get_mail_sender`.
 
 ### Environment variables
 
@@ -266,6 +391,15 @@ 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` |
+| `MAIL_BACKEND` | `memory` (default) or `smtp` |
+| `MAIL_FROM_ADDRESS`, `MAIL_FROM_NAME` | Default sender. The address is required by `smtp` |
+| `MAIL_SMTP_HOST`, `MAIL_SMTP_PORT` | The relay. Port defaults to `587` |
+| `MAIL_SMTP_STARTTLS` | Upgrade the connection with STARTTLS. Defaults to `true` |
+| `MAIL_SMTP_USERNAME`, `MAIL_SMTP_PASSWORD` | Only for relays that require a login |
+| `MAIL_SMTP_TIMEOUT_SECONDS` | Connection and command timeout. Defaults to `30` |
 
 ## Wiring it into an application
 
@@ -389,11 +523,11 @@ poetry install --with dev --all-extras
 poetry run pytest -q
 ```
 
-Current baseline: **434 tests passing** (version 3.9.1). Async tests use
+Current baseline: **621 tests passing** (version 3.13.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
-importing `persistence_kit` drags in fastapi, pyjwt or boto3.
+importing `persistence_kit` drags in fastapi, pyjwt, boto3 or jinja2.
 
 ## Releasing
 
@@ -427,5 +561,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.11.0 → persistence_kit-3.13.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.13.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.13.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)