babelqueue 1.11.0__tar.gz → 1.13.0__tar.gz

{babelqueue-1.11.0 → babelqueue-1.13.0}/CHANGELOG.md

@@ -9,6 +9,62 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [1.13.0] - 2026-06-21
+
+### Added
+- **Runtime GDPR field encryption** (ADR-0030) — the optional `babelqueue.gdpr` module ports the Go
+  reference to Python: the SDK-enforcement half of governed PII. The babelqueue-registry only
+  **declares** and **audits** `x-gdpr-sensitive` fields (and can **mask** them for safe logging);
+  this module **enforces** them on the wire — a producer encrypts each marked leaf before publish, a
+  consumer decrypts it after decode. Strictly **opt-in**: a producer/consumer that never calls
+  `protect`/`unprotect` is unchanged. The **envelope stays frozen** (GR-1): only **values inside
+  `data`** change — a sensitive leaf's value becomes a ciphertext **string** — so `data` stays pure
+  JSON (an SDK without the key still carries the envelope), `meta.schema_version` stays `1`, and
+  `trace_id` is untouched (GR-4). The core stays **stdlib-only** (GR-7): Python's standard library
+  has **no AES-GCM**, so the module ships **no** concrete cipher and pulls **no** crypto dependency
+  — `Cipher` is a caller-provided `typing.Protocol` (`encrypt(bytes) -> str` / `decrypt(str) ->
+  bytes`) bound to a KMS / Vault / HSM / tokenisation service, or to a local AES-256-GCM via the
+  optional `cryptography` library (new `babelqueue[gdpr]` extra, documented in the README — still
+  **not** a core dependency). `protect(data, schema, cipher)` canonically JSON-encodes each marked
+  leaf and replaces it with the cipher's ciphertext string **in place**; `unprotect(...)` is the
+  exact inverse, restoring `data` **byte-for-byte**. The marked paths come from the **same per-URN
+  schema** the validator already loads — `babelqueue.schema.sensitive_paths` walks nested objects
+  (`profile.full_name`), array items (`addresses[].line`), container, and root marks, and the
+  `x-gdpr-sensitive` keyword is **validation-neutral** (annotating a schema is never breaking). An
+  absent marked field is skipped (not an error); a re-run `unprotect` on already-cleartext data is a
+  no-op (non-string leaves are left alone); a wrong key / tampered / non-ciphertext value raises the
+  new `babelqueue.DecryptError` so the consumer fails the message (retry / dead-letter) rather than
+  handle unreadable PII. Validate cleartext **before** `protect` / **after** `unprotect`, since a
+  schema constraining a sensitive field would reject the ciphertext string. Unit-tested without any
+  crypto dependency (a stdlib-only authenticated fake cipher) for round-trip exactness across
+  nested/array/container/root marks, skips, idempotent re-runs, frozen-envelope decode/validate, and
+  wrong-key failure. The envelope is unchanged (`schema_version: 1`); this is purely additive.
+
+## [1.12.0] - 2026-06-21
+
+### Added
+- **Transactional outbox helper** (ADR-0029) — the optional `babelqueue.outbox` module ports the
+  PHP `BabelQueue\Outbox` helper to Python, removing the producer **dual write**: the message is
+  persisted **into your database, in the same transaction** as the business data (so it commits or
+  rolls back atomically with it), and a separate **relay** publishes the durable rows afterwards.
+  No distributed transaction; exactly-once *handoff* into the broker, then at-least-once on the wire
+  (the consumer dedupes on `meta.id` via the idempotency helper, the consumer-side mirror, ADR-0022).
+  The core stays **stdlib-only** (GR-7): `OutboxStore` is an abstract `typing.Protocol` the caller
+  binds to their own DB — the module ships only the in-memory `InMemoryOutboxStore` reference and
+  pulls in **no** DB driver. `Outbox.write(envelope)` encodes via the frozen `EnvelopeCodec` and
+  delegates to `OutboxStore.save` **inside the transaction the caller already opened** — it does not
+  begin/commit anything (the caller owns the transaction boundary). `OutboxRelay.flush()` publishes
+  one batch through the existing publish-only `Transport`, marking each row published **only after**
+  the transport accepts it, or failed (caught → `mark_failed`, row left pending, with a bounded
+  linear backoff via an injectable sleeper) so one poison row never blocks the batch;
+  `OutboxRelay.drain()` loops while a pass makes progress, with a safety ceiling. The relay
+  publishes the **stored bytes verbatim** — it never decodes, rebuilds or re-encodes the envelope —
+  so `trace_id` is preserved end-to-end and the body is byte-compatible across SDKs (GR-1/GR-4/GR-5).
+  Unit-tested without a broker (write stores the encoded envelope byte-identical; relay publishes via
+  a fake `Transport` + marks published; a raising publish → `mark_failed`, row still pending, batch
+  continues; `drain` loops to empty and stops on no-progress; backoff grows linearly and caps via the
+  injected sleeper). The envelope is unchanged (`schema_version: 1`); this is purely additive.
+
 ## [1.11.0] - 2026-06-21
 
 ### Added

{babelqueue-1.11.0 → babelqueue-1.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: babelqueue
-Version: 1.11.0
+Version: 1.13.0
 Summary: Polyglot Queues, Simplified — the Python core: the canonical BabelQueue wire-envelope codec, contracts and dead-letter helpers.
 Project-URL: Homepage, https://babelqueue.com
 Project-URL: Source, https://github.com/BabelQueue/babelqueue-python
@@ -38,6 +38,8 @@ Requires-Dist: pytest>=7; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
 Provides-Extra: django
 Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: gdpr
+Requires-Dist: cryptography>=42; extra == 'gdpr'
 Provides-Extra: kafka
 Requires-Dist: confluent-kafka>=2.3; extra == 'kafka'
 Provides-Extra: otel
@@ -234,6 +236,47 @@ def on_created(data, meta): ...
 python manage.py babelqueue_worker --queue orders          # run the consumer
 ```
 
+## Transactional outbox (optional)
+
+The `babelqueue.outbox` helper (ADR-0029) removes the producer **dual write**: "commit the
+business row" and "publish to the broker" are two systems that can disagree on a crash. Instead the
+message is persisted **into your database, in the same transaction** as the business data — so it
+commits or rolls back atomically with it — and a separate **relay** publishes the durable rows
+afterwards. No distributed transaction; exactly-once *handoff* into the broker, then at-least-once
+on the wire (the consumer dedupes on `meta.id` — see the idempotency helper, the mirror of this).
+
+The core stays **stdlib-only**: `OutboxStore` is an abstract `Protocol` you bind to **your own DB**
+(the core ships no driver). The stored value is the `EnvelopeCodec`-encoded envelope **byte-for-byte
+unchanged** (frozen, `schema_version: 1`); the relay publishes those exact bytes — it never decodes,
+rebuilds or re-encodes — so `trace_id` is preserved end-to-end.
+
+```python
+from babelqueue import BabelQueue, EnvelopeCodec
+from babelqueue.outbox import Outbox, OutboxRelay, InMemoryOutboxStore
+
+store = InMemoryOutboxStore()          # production: your own OutboxStore adapter, DB-backed
+outbox = Outbox(store)
+
+# write side — YOU own the transaction boundary (this is the whole point):
+with db.transaction():                 # your own open transaction
+    db.insert_order(order)             # the business write
+    envelope = EnvelopeCodec.make("urn:babel:orders:created", {"order_id": 1042}, queue="orders")
+    outbox.write(envelope)             # same connection, same tx — both, or neither
+
+# read/publish side — run on a short interval, after the business tx commits:
+app = BabelQueue("redis://localhost:6379/0", queue="orders")
+relay = OutboxRelay(app.transport, store)
+relay.drain()                          # publish all pending rows; flush() does one batch
+```
+
+`Outbox.write` only encodes and calls `OutboxStore.save` — it does **not** begin or commit anything.
+A `save` runs inside the transaction you already opened; you commit both together. `OutboxRelay`
+marks a row published only **after** the transport accepts it; a publish that raises is recorded via
+`mark_failed` (with a bounded, injectable-sleeper backoff) and left pending for a later pass, so one
+poison row never blocks the batch. Implement `OutboxStore` over your DB (claim rows oldest-first,
+ideally with `SELECT … FOR UPDATE SKIP LOCKED` so two relays don't double-publish); `InMemoryOutboxStore`
+is the reference for tests and single-process demos (no real transaction).
+
 ## OpenTelemetry tracing (optional)
 
 `pip install "babelqueue[otel]"` adds the optional `babelqueue.otel` module — the core never
@@ -270,6 +313,65 @@ with bare-value back-compat), RabbitMQ (AMQP header table) and SQS (`MessageAttr
 transports; where a transport can't carry it, propagation degrades cleanly to v0.1 `trace_id`
 correlation with no error.
 
+## GDPR field encryption (optional)
+
+The optional `babelqueue.gdpr` module is the runtime, SDK-enforcement half of ADR-0030: it
+encrypts the `data` fields a registry declared `x-gdpr-sensitive`. The babelqueue-registry only
+**declares** and **audits** sensitivity (and can **mask** for safe logging); this module
+**enforces** it on the wire — a producer encrypts each marked leaf before publish, a consumer
+decrypts it after decode. It is strictly **opt-in**: if you never call `protect`/`unprotect`,
+nothing changes.
+
+The envelope stays **frozen** (`schema_version: 1`): only the **values inside `data`** change — a
+sensitive leaf's value becomes a ciphertext **string**. `data` stays pure JSON, so an SDK without
+the key still carries the envelope (it just can't read the protected fields), and `trace_id` is
+never touched. Which fields are sensitive lives in the **schema**, not the message.
+
+Because Python's standard library has **no AES-GCM**, the core ships **no** cipher and pulls **no**
+crypto dependency (GR-7). `Cipher` is a caller-provided `Protocol` you bind to a KMS / Vault / HSM /
+tokenisation service, or to a local AES-256-GCM via the optional `cryptography` library
+(`pip install "babelqueue[gdpr]"` — still **not** a core dependency):
+
+```python
+import base64, os
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+class AesGcmCipher:
+    def __init__(self, key: bytes) -> None:       # 16/24/32-byte key — the CALLER's
+        self._aead = AESGCM(key)
+
+    def encrypt(self, plaintext: bytes) -> str:
+        nonce = os.urandom(12)
+        return base64.b64encode(nonce + self._aead.encrypt(nonce, plaintext, None)).decode("ascii")
+
+    def decrypt(self, ciphertext: str) -> bytes:
+        raw = base64.b64decode(ciphertext)
+        return self._aead.decrypt(raw[:12], raw[12:], None)   # raises on wrong key / tamper
+```
+
+Wire it around the codec — validate **cleartext** (before `protect`, after `unprotect`), since a
+schema that constrains a sensitive field would reject the ciphertext string:
+
+```python
+from babelqueue import EnvelopeCodec
+from babelqueue.gdpr import protect, unprotect
+
+# producer: encrypt marked leaves in place, then encode
+protect(data, schema, cipher)
+body = EnvelopeCodec.encode(EnvelopeCodec.make("urn:babel:orders:created", data, queue="orders"))
+
+# consumer: decode, then decrypt marked leaves in place before the handler reads data
+envelope = EnvelopeCodec.decode(body)
+unprotect(envelope["data"], schema, cipher)
+```
+
+`schema` is the same per-URN JSON Schema the validator uses; `babelqueue.schema.sensitive_paths`
+locates every `x-gdpr-sensitive` leaf (nested objects, `addresses[].line` array items, container or
+root marks). An absent marked field is skipped; a re-run `unprotect` on cleartext is a no-op
+(non-string leaves are left alone); a wrong key / tampered ciphertext raises
+`babelqueue.DecryptError` so the consumer fails the message (retry / dead-letter) rather than
+process unreadable PII. The round-trip restores `data` **byte-for-byte**.
+
 ## What's here
 
 The codec/contracts/dead-letter (zero-dep core), the `BabelQueue` runtime

{babelqueue-1.11.0 → babelqueue-1.13.0}/README.md

@@ -182,6 +182,47 @@ def on_created(data, meta): ...
 python manage.py babelqueue_worker --queue orders          # run the consumer
 ```
 
+## Transactional outbox (optional)
+
+The `babelqueue.outbox` helper (ADR-0029) removes the producer **dual write**: "commit the
+business row" and "publish to the broker" are two systems that can disagree on a crash. Instead the
+message is persisted **into your database, in the same transaction** as the business data — so it
+commits or rolls back atomically with it — and a separate **relay** publishes the durable rows
+afterwards. No distributed transaction; exactly-once *handoff* into the broker, then at-least-once
+on the wire (the consumer dedupes on `meta.id` — see the idempotency helper, the mirror of this).
+
+The core stays **stdlib-only**: `OutboxStore` is an abstract `Protocol` you bind to **your own DB**
+(the core ships no driver). The stored value is the `EnvelopeCodec`-encoded envelope **byte-for-byte
+unchanged** (frozen, `schema_version: 1`); the relay publishes those exact bytes — it never decodes,
+rebuilds or re-encodes — so `trace_id` is preserved end-to-end.
+
+```python
+from babelqueue import BabelQueue, EnvelopeCodec
+from babelqueue.outbox import Outbox, OutboxRelay, InMemoryOutboxStore
+
+store = InMemoryOutboxStore()          # production: your own OutboxStore adapter, DB-backed
+outbox = Outbox(store)
+
+# write side — YOU own the transaction boundary (this is the whole point):
+with db.transaction():                 # your own open transaction
+    db.insert_order(order)             # the business write
+    envelope = EnvelopeCodec.make("urn:babel:orders:created", {"order_id": 1042}, queue="orders")
+    outbox.write(envelope)             # same connection, same tx — both, or neither
+
+# read/publish side — run on a short interval, after the business tx commits:
+app = BabelQueue("redis://localhost:6379/0", queue="orders")
+relay = OutboxRelay(app.transport, store)
+relay.drain()                          # publish all pending rows; flush() does one batch
+```
+
+`Outbox.write` only encodes and calls `OutboxStore.save` — it does **not** begin or commit anything.
+A `save` runs inside the transaction you already opened; you commit both together. `OutboxRelay`
+marks a row published only **after** the transport accepts it; a publish that raises is recorded via
+`mark_failed` (with a bounded, injectable-sleeper backoff) and left pending for a later pass, so one
+poison row never blocks the batch. Implement `OutboxStore` over your DB (claim rows oldest-first,
+ideally with `SELECT … FOR UPDATE SKIP LOCKED` so two relays don't double-publish); `InMemoryOutboxStore`
+is the reference for tests and single-process demos (no real transaction).
+
 ## OpenTelemetry tracing (optional)
 
 `pip install "babelqueue[otel]"` adds the optional `babelqueue.otel` module — the core never
@@ -218,6 +259,65 @@ with bare-value back-compat), RabbitMQ (AMQP header table) and SQS (`MessageAttr
 transports; where a transport can't carry it, propagation degrades cleanly to v0.1 `trace_id`
 correlation with no error.
 
+## GDPR field encryption (optional)
+
+The optional `babelqueue.gdpr` module is the runtime, SDK-enforcement half of ADR-0030: it
+encrypts the `data` fields a registry declared `x-gdpr-sensitive`. The babelqueue-registry only
+**declares** and **audits** sensitivity (and can **mask** for safe logging); this module
+**enforces** it on the wire — a producer encrypts each marked leaf before publish, a consumer
+decrypts it after decode. It is strictly **opt-in**: if you never call `protect`/`unprotect`,
+nothing changes.
+
+The envelope stays **frozen** (`schema_version: 1`): only the **values inside `data`** change — a
+sensitive leaf's value becomes a ciphertext **string**. `data` stays pure JSON, so an SDK without
+the key still carries the envelope (it just can't read the protected fields), and `trace_id` is
+never touched. Which fields are sensitive lives in the **schema**, not the message.
+
+Because Python's standard library has **no AES-GCM**, the core ships **no** cipher and pulls **no**
+crypto dependency (GR-7). `Cipher` is a caller-provided `Protocol` you bind to a KMS / Vault / HSM /
+tokenisation service, or to a local AES-256-GCM via the optional `cryptography` library
+(`pip install "babelqueue[gdpr]"` — still **not** a core dependency):
+
+```python
+import base64, os
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+class AesGcmCipher:
+    def __init__(self, key: bytes) -> None:       # 16/24/32-byte key — the CALLER's
+        self._aead = AESGCM(key)
+
+    def encrypt(self, plaintext: bytes) -> str:
+        nonce = os.urandom(12)
+        return base64.b64encode(nonce + self._aead.encrypt(nonce, plaintext, None)).decode("ascii")
+
+    def decrypt(self, ciphertext: str) -> bytes:
+        raw = base64.b64decode(ciphertext)
+        return self._aead.decrypt(raw[:12], raw[12:], None)   # raises on wrong key / tamper
+```
+
+Wire it around the codec — validate **cleartext** (before `protect`, after `unprotect`), since a
+schema that constrains a sensitive field would reject the ciphertext string:
+
+```python
+from babelqueue import EnvelopeCodec
+from babelqueue.gdpr import protect, unprotect
+
+# producer: encrypt marked leaves in place, then encode
+protect(data, schema, cipher)
+body = EnvelopeCodec.encode(EnvelopeCodec.make("urn:babel:orders:created", data, queue="orders"))
+
+# consumer: decode, then decrypt marked leaves in place before the handler reads data
+envelope = EnvelopeCodec.decode(body)
+unprotect(envelope["data"], schema, cipher)
+```
+
+`schema` is the same per-URN JSON Schema the validator uses; `babelqueue.schema.sensitive_paths`
+locates every `x-gdpr-sensitive` leaf (nested objects, `addresses[].line` array items, container or
+root marks). An absent marked field is skipped; a re-run `unprotect` on cleartext is a no-op
+(non-string leaves are left alone); a wrong key / tampered ciphertext raises
+`babelqueue.DecryptError` so the consumer fails the message (retry / dead-letter) rather than
+process unreadable PII. The round-trip restores `data` **byte-for-byte**.
+
 ## What's here
 
 The codec/contracts/dead-letter (zero-dep core), the `BabelQueue` runtime

{babelqueue-1.11.0 → babelqueue-1.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "1.11.0"
+version = "1.13.0"
 description = "Polyglot Queues, Simplified — the Python core: the canonical BabelQueue wire-envelope codec, contracts and dead-letter helpers."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -37,6 +37,9 @@ pulsar = ["pulsar-client>=3.4"]
 kafka = ["confluent-kafka>=2.3"]
 artemis = ["python-qpid-proton>=0.39"]
 otel = ["opentelemetry-api>=1.20"]
+# Only for the documented bring-your-own AES-256-GCM reference cipher (ADR-0030). The core never
+# imports it; protect/unprotect take a caller-provided Cipher Protocol, so this is NOT a core dep.
+gdpr = ["cryptography>=42"]
 celery = ["celery>=5"]
 django = ["django>=4.2"]
 dev = ["pytest>=7", "pytest-cov>=4", "mypy>=1.8", "ruff>=0.5"]

{babelqueue-1.11.0 → babelqueue-1.13.0}/src/babelqueue/__init__.py

@@ -11,18 +11,27 @@ and dead-letter helpers. Framework adapters (Celery, Django, ...) build on this.
 
 from __future__ import annotations
 
-from . import dead_letter, headers, idempotency, redrive, replay
+from . import dead_letter, gdpr, headers, idempotency, outbox, redrive, replay
 from .app import BabelQueue
 from .codec import SCHEMA_VERSION, SOURCE_LANG, EnvelopeCodec
 from .contracts import HasTraceId, PolyglotMessage
+from .gdpr import Cipher, protect, unprotect
 from .headers import headers_from_context
 from .idempotency import IdempotencyStore, InMemoryStore
-from .exceptions import BabelQueueError, UnknownUrnError
+from .outbox import (
+    InMemoryOutboxStore,
+    Outbox,
+    OutboxRecord,
+    OutboxRelay,
+    OutboxRelayResult,
+    OutboxStore,
+)
+from .exceptions import BabelQueueError, DecryptError, UnknownUrnError
 from .replay import HEADER_REPLAY_BYPASS, bypass_external_effects, is_replay
 from .routing import UnknownUrnStrategy
 from .transport import HeaderPublisher, InMemoryTransport, ReceivedMessage, Transport
 
-__version__ = "1.11.0"
+__version__ = "1.13.0"
 
 __all__ = [
     "BabelQueue",
@@ -38,9 +47,21 @@ __all__ = [
     "HeaderPublisher",
     "BabelQueueError",
     "UnknownUrnError",
+    "DecryptError",
+    "gdpr",
+    "Cipher",
+    "protect",
+    "unprotect",
     "dead_letter",
     "headers",
     "idempotency",
+    "outbox",
+    "Outbox",
+    "OutboxStore",
+    "OutboxRecord",
+    "OutboxRelay",
+    "OutboxRelayResult",
+    "InMemoryOutboxStore",
     "redrive",
     "replay",
     "is_replay",

{babelqueue-1.11.0 → babelqueue-1.13.0}/src/babelqueue/exceptions.py

@@ -23,3 +23,15 @@ class InvalidPayloadError(BabelQueueError):
         super().__init__(f"data for {urn!r} does not match its URN schema: {violation}")
         self.urn = urn
         self.violation = violation
+
+
+class DecryptError(BabelQueueError):
+    """A protected ``x-gdpr-sensitive`` field could not be restored on the consume side (ADR-0030).
+
+    Raised by :func:`babelqueue.gdpr.unprotect` when a marked leaf is a ciphertext string the
+    :class:`~babelqueue.gdpr.Cipher` cannot open — a wrong key, a tampered/garbled ciphertext, or a
+    value whose decrypted bytes are not the JSON the producer encoded. The Python mirror of the Go
+    ``gdpr.ErrDecrypt``: a missing field is skipped (not an error), but an *unreadable* one stops
+    ``unprotect`` so the consumer fails the message (retry / dead-letter) rather than handle
+    unreadable PII.
+    """

babelqueue-1.13.0/src/babelqueue/gdpr.py

@@ -0,0 +1,245 @@
+"""Optional runtime GDPR field encryption (ADR-0030): the SDK-enforcement half.
+
+The Python mirror of the Go ``gdpr`` package — the reference the SDKs share. The
+babelqueue-registry only **declares** and **audits** which ``data`` fields are sensitive (the
+``x-gdpr-sensitive`` schema keyword) and can **mask** them for safe logging; this module
+**enforces** that on the wire — a producer encrypts each marked leaf before publish, a consumer
+decrypts it after decode. It is strictly **opt-in**: a producer/consumer that never calls
+:func:`protect`/:func:`unprotect` behaves exactly as before.
+
+The contract is deliberately tight so every SDK stays byte-compatible:
+
+- **The envelope stays frozen (GR-1).** :func:`protect` mutates only **values inside ``data``**: a
+  sensitive leaf's value becomes a ciphertext **string**. It never adds, renames, removes or
+  retypes an envelope field; ``meta.schema_version`` stays ``1``; ``trace_id`` is untouched (GR-4).
+  ``data`` stays **pure JSON** (GR-3) — a JSON string is still pure JSON, so any SDK can carry the
+  envelope even without the key (it just can't read the protected fields).
+- **Zero heavy dependencies (GR-7).** Python's standard library has **no AES-GCM**, so the core
+  ships **no** concrete cipher and pulls **no** crypto dependency. :class:`Cipher` is a
+  caller-provided :class:`typing.Protocol` — bind it to a KMS, Vault transit, an HSM, a
+  tokenisation service, or a local AES-GCM built on the optional ``cryptography`` library (see the
+  bring-your-own-cipher example below). The crypto dependency lives in the *caller's* code, never
+  in this core.
+
+The sensitive paths come from the **same per-URN schema** the produce/consume validation path
+already loads (:func:`babelqueue.schema.sensitive_paths`) — the ``x-gdpr-sensitive`` marks ride on
+it. Validate **cleartext**: run :func:`babelqueue.schema.validate` **before** :func:`protect` on
+the producer and **after** :func:`unprotect` on the consumer, because a schema that constrains a
+sensitive field (``minLength``, ``enum``, …) would otherwise reject the ciphertext string.
+
+Typical wiring (producer)::
+
+    from babelqueue import EnvelopeCodec
+    from babelqueue.gdpr import protect
+
+    data = {"order_id": 1042, "email": "alice@example.com"}
+    # validate(provider, urn, data)          # optional: validate cleartext first
+    protect(data, schema, cipher)            # encrypt marked leaves IN PLACE
+    body = EnvelopeCodec.encode(EnvelopeCodec.make(urn, data))   # ciphertext rides inside data
+
+and the inverse on the consumer, after decode and before the handler reads ``data``::
+
+    from babelqueue.gdpr import unprotect
+
+    envelope = EnvelopeCodec.decode(body)
+    unprotect(envelope["data"], schema, cipher)   # decrypt marked leaves IN PLACE
+    # validate(provider, urn, envelope["data"])   # optional: validate cleartext after
+
+Bring-your-own AES-256-GCM cipher (NOT part of this core — ``pip install cryptography``)::
+
+    import base64, os
+    from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+    class AesGcmCipher:
+        '''A reference Cipher: AES-256-GCM, random 12-byte nonce prepended, base64 out.
+        The 32-byte key is the CALLER's; this does no key management or rotation.'''
+
+        def __init__(self, key: bytes) -> None:
+            self._aead = AESGCM(key)          # key must be 16, 24, or 32 bytes
+
+        def encrypt(self, plaintext: bytes) -> str:
+            nonce = os.urandom(12)
+            sealed = self._aead.encrypt(nonce, plaintext, None)
+            return base64.b64encode(nonce + sealed).decode("ascii")
+
+        def decrypt(self, ciphertext: str) -> bytes:
+            raw = base64.b64decode(ciphertext)
+            nonce, sealed = raw[:12], raw[12:]
+            return self._aead.decrypt(nonce, sealed, None)   # raises on wrong key/tamper
+
+The same plaintext MAY encrypt to a different string each call (the random nonce is expected and
+good); :meth:`Cipher.decrypt` restores the exact bytes :meth:`Cipher.encrypt` was given, and a
+wrong-key / tampered input MUST raise (GCM authentication) — :func:`unprotect` turns any such raise
+into :class:`~babelqueue.exceptions.DecryptError`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, List, MutableMapping, MutableSequence, Optional, Protocol, Tuple, runtime_checkable
+
+from .exceptions import DecryptError
+from .schema import sensitive_paths
+
+__all__ = ["Cipher", "protect", "unprotect"]
+
+
+@runtime_checkable
+class Cipher(Protocol):
+    """The field-level protection primitive the **caller** provides — a seam onto a KMS, Vault
+    transit, an HSM, a tokenisation service, or a local AES-GCM (see the module docstring). Keeping
+    this a Protocol is what holds GR-7: this core never imports a crypto library; only the caller's
+    concrete cipher does.
+
+    Contract for an implementation:
+
+    - :meth:`encrypt` takes the canonical JSON bytes of one field value (see :func:`protect`) and
+      returns the ciphertext as a **str** that is valid for placement inside a JSON document (e.g.
+      base64). The same plaintext MAY encrypt to a different string each call (a random nonce/IV is
+      expected and good).
+    - :meth:`decrypt` is the exact inverse: given a string :meth:`encrypt` produced it returns the
+      original JSON bytes byte-for-byte. A string it did not produce, or one produced under a
+      different key, MUST **raise** rather than return silent garbage, so a wrong-key consume fails
+      loudly (:func:`unprotect` wraps the raise in :class:`~babelqueue.exceptions.DecryptError`).
+    - Both SHOULD be safe for concurrent use; a producer/consumer may fan one cipher across threads.
+    """
+
+    def encrypt(self, plaintext: bytes) -> str:
+        """Protect one field value (its canonical JSON bytes) → a JSON-safe ciphertext string."""
+        ...
+
+    def decrypt(self, ciphertext: str) -> bytes:
+        """Reverse :meth:`encrypt`, returning the original field-value JSON bytes."""
+        ...
+
+
+def protect(data: MutableMapping[str, Any], schema: Any, cipher: Cipher) -> None:
+    """Encrypt, in place, every value in ``data`` at a path the schema marked ``x-gdpr-sensitive``.
+
+    The producer-side step — run it after building ``data`` and before encode/publish. Each marked
+    leaf's value is canonically JSON-encoded and replaced by ``cipher.encrypt``'s ciphertext
+    **string**; the envelope frame, non-sensitive fields, and everything else are untouched (GR-1).
+
+    A marked path absent from ``data`` is skipped (not an error) — schemas evolve and a message need
+    not carry every optional field. ``data`` may be empty (no-op). A ``None`` schema or one with no
+    marks is a no-op (nothing is sensitive). A container mark (a whole object/array marked
+    sensitive) is supported: the entire sub-value is encoded and encrypted as one ciphertext string.
+
+    On any cipher error this propagates and leaves ``data`` partially protected; treat a raised
+    error as fatal for that message (do not publish it).
+    """
+    _walk(data, schema, cipher, _encrypt_leaf)
+
+
+def unprotect(data: MutableMapping[str, Any], schema: Any, cipher: Cipher) -> None:
+    """Decrypt, in place, every value in ``data`` at an ``x-gdpr-sensitive`` path — the consumer-side
+    inverse of :func:`protect`. Run it after decode and before the handler reads ``data``.
+
+    An absent path is skipped. A leaf that is **not a string** — it was never protected, or this is
+    a re-run after a successful :func:`unprotect` — is left as-is, so re-invoking on already-cleartext
+    data is safe (idempotent for non-string leaves). A string the cipher cannot open (wrong key,
+    tampered, or not a ciphertext) raises :class:`~babelqueue.exceptions.DecryptError` — the consumer
+    should fail the message (retry / dead-letter) rather than process unreadable PII.
+    """
+    _walk(data, schema, cipher, _decrypt_leaf)
+
+
+# A leaf op transforms one sensitive leaf value (encrypt or decrypt). It returns ``(new_value, ok)``:
+# ``ok=False`` means the value should be left in place untouched.
+_LeafOp = Callable[[Any, Cipher], Tuple[Any, bool]]
+
+
+def _walk(data: Any, schema: Any, cipher: Optional[Cipher], op: _LeafOp) -> None:
+    """Drive ``op`` over every ``x-gdpr-sensitive`` path the schema declares, resolving each path
+    against ``data`` itself (NOT by re-walking the schema over the value), so the operation touches
+    exactly the declared leaves — non-sensitive siblings are never read or copied."""
+    if data is None or schema is None or cipher is None:
+        return
+    for sp in sensitive_paths(schema):
+        _apply_at_path(data, _parse_path(sp.path), cipher, op)
+
+
+# One step of a sensitive path: ``(key, is_array)``. ``"addresses[].line"`` parses to
+# ``[("addresses", True), ("line", False)]``; the ``[]`` marker means array-descent into every
+# element before the next segment.
+_Segment = Tuple[str, bool]
+
+
+def _parse_path(path: str) -> List[_Segment]:
+    """Split a sensitive path (``"email"``, ``"profile.full_name"``, ``"addresses[].line"``) into
+    segments. A trailing ``[]`` on a part binds to it as array-descent. A root mark (path ``""``)
+    yields no segments — there is no addressable leaf for it inside ``data``, so it is skipped."""
+    if path == "":
+        return []
+    segments: List[_Segment] = []
+    for part in path.split("."):
+        if len(part) >= 2 and part.endswith("[]"):
+            segments.append((part[:-2], True))
+        else:
+            segments.append((part, False))
+    return segments
+
+
+def _apply_at_path(node: Any, segments: List[_Segment], cipher: Cipher, op: _LeafOp) -> None:
+    """Resolve ``segments`` against ``node`` and run ``op`` on the leaf(s). It descends objects by
+    key and, when a segment is an array, fans out over every element. An absent key or a type
+    mismatch (a path that does not exist in this particular message) is skipped silently — schemas
+    describe the union of possible shapes; a given message need not contain every field."""
+    if not segments:
+        return  # root mark or exhausted path with no leaf key — nothing addressable in data
+    key, is_array = segments[0]
+    if not isinstance(node, MutableMapping):
+        return  # expected an object here but the message has something else — skip
+    if key not in node:
+        return  # absent field — skip (not an error)
+
+    child = node[key]
+    last = len(segments) == 1
+
+    if is_array:
+        if not isinstance(child, MutableSequence):
+            return  # declared array but message has a non-array — skip
+        for i, elem in enumerate(child):
+            if last:
+                new_value, ok = op(elem, cipher)
+                if ok:
+                    child[i] = new_value
+            else:
+                _apply_at_path(elem, segments[1:], cipher, op)
+        return
+
+    if last:
+        new_value, ok = op(child, cipher)
+        if ok:
+            node[key] = new_value
+        return
+    _apply_at_path(child, segments[1:], cipher, op)
+
+
+def _encrypt_leaf(value: Any, cipher: Cipher) -> Tuple[Any, bool]:
+    """Canonically JSON-encode one field value and replace it with the cipher's ciphertext string.
+    The JSON encoding is what makes the round-trip exact: :func:`unprotect`'s ``json.loads`` restores
+    the same decoded-JSON value (``float`` for numbers, ``dict`` for objects, …) the codec would
+    have produced, so protect → unprotect is byte-for-byte. ``sort_keys`` + compact separators give
+    one canonical encoding, mirroring the Go reference's ``json.Marshal``."""
+    plaintext = json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return cipher.encrypt(plaintext), True
+
+
+def _decrypt_leaf(value: Any, cipher: Cipher) -> Tuple[Any, bool]:
+    """Reverse :func:`_encrypt_leaf`. A non-string leaf is left untouched (``ok=False``) so
+    :func:`unprotect` is safe to re-run on already-cleartext data; a string that fails to open or to
+    JSON-decode raises :class:`~babelqueue.exceptions.DecryptError` so the consumer fails the message
+    rather than handle unreadable PII."""
+    if not isinstance(value, str):
+        # Not a ciphertext string (already cleartext, or never protected) — leave as-is.
+        return None, False
+    try:
+        plaintext = cipher.decrypt(value)
+    except Exception as exc:  # noqa: BLE001 — any cipher failure is a decrypt failure for the caller
+        raise DecryptError(f"cannot decrypt a protected field: {exc}") from exc
+    try:
+        restored = json.loads(plaintext)
+    except (ValueError, TypeError) as exc:
+        raise DecryptError(f"decrypted plaintext is not JSON: {exc}") from exc
+    return restored, True