feat(gdpr): runtime field encryption for x-gdpr-sensitive — Java core (ADR-0030)

The SDK-enforcement half of GDPR governance (mirrors the Go reference). New
com.babelqueue.gdpr: a caller-bound Cipher interface (encrypt/decrypt onto
KMS/Vault) + a JDK-only AesGcmCipher reference (javax.crypto, AES-256-GCM), and
Gdpr.protect/unprotect that encrypt/decrypt exactly the schema's x-gdpr-sensitive
leaves in place (nested + array + root), byte-for-byte round-trip, wrong key ->
DecryptException. SensitivePaths.of parses x-gdpr-sensitive (validation-neutral);
a small public JsonValues bridges the package-private codec for canonical leaf
round-trips. data stays pure JSON (ciphertext string) so the envelope is frozen
(GR-1, schema_version 1, trace_id preserved); the Cipher seam keeps the core
zero-dep (GR-7). Opt-in; schema validation on cleartext. v1.7.0.

Author: muhammetsafak

CHANGELOG.md

@@ -9,6 +9,34 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-06-21
+
+### Added
+- **Runtime GDPR field encryption** (ADR-0030) in the new optional `com.babelqueue.gdpr`
+  module — the **SDK-enforcement** half of the registry's `x-gdpr-sensitive` declaration.
+  babelqueue-registry only *declares* and audits which `data` fields are personal data; this
+  module *enforces* it on the wire: a producer encrypts each marked leaf before publish, a
+  consumer decrypts it after decode. It is the Java mirror of the Go reference, so every SDK
+  round-trips byte-for-byte. Standalone and **opt-in**.
+  - `Cipher` is a **caller-provided** interface (`encrypt(byte[])` / `decrypt(String)`) — a
+    seam onto KMS/Vault/HSM/tokenisation, so the core pulls **no** crypto dependency (GR-7).
+    `AesGcmCipher` is a JDK-only reference (`javax.crypto`, AES-256-GCM, a fresh random 12-byte
+    IV prepended, Base64); the caller owns the key. A wrong key or tampered ciphertext fails GCM
+    authentication and throws rather than returning corrupt plaintext.
+  - `Gdpr.protect(data, schema, cipher)` / `Gdpr.unprotect(...)` rewrite each `x-gdpr-sensitive`
+    leaf **in place**: the value is canonically JSON-encoded then replaced by the ciphertext
+    **string**, and `unprotect` decodes the decrypted bytes back — so the round-trip is
+    **byte-for-byte** (a number restores to a number, an object to an object). An absent path is
+    skipped; a non-string leaf in `unprotect` is left untouched (idempotent re-runs); a value the
+    cipher cannot open throws `DecryptException` so the message takes retry / dead-letter.
+  - `SensitivePaths.of(schema)` (+ the `SensitivePath` record) in `com.babelqueue.schema` walk a
+    decoded JSON Schema for the `x-gdpr-sensitive` marks (boolean `true` or a non-empty string
+    category), descending nested objects, array items (`field[]`) and the root. The keyword is
+    **validation-neutral** — annotating a schema is never a breaking change.
+  - The wire envelope stays **frozen**: only the *value* of a sensitive field changes (to a
+    ciphertext string), so `data` is still pure JSON (GR-3), `meta.schema_version` stays `1` and
+    `trace_id` is untouched (GR-4). This is additive and opt-in.
+
 ## [1.6.0] - 2026-06-21
 
 ### Added

README.md

@@ -146,6 +146,49 @@ the broker, then at-least-once on the wire as always — consumers still dedupe
 (`SELECT … FOR UPDATE SKIP LOCKED`) is the adapter's job; the in-memory reference store does
 not implement it.
 
+### GDPR field encryption (optional)
+
+The `com.babelqueue.gdpr` helper (ADR-0030) is the **runtime, SDK-enforcement** half of
+the registry's `x-gdpr-sensitive` declaration: a producer encrypts each marked `data`
+field before publish, a consumer decrypts it after decode. The registry only *declares*
+which fields are personal data; this enforces it on the wire. It is standalone and
+**opt-in** — call it, or don't.
+
+```java
+import com.babelqueue.gdpr.*;
+import com.babelqueue.schema.*;
+
+// The Cipher is YOURS — a seam onto KMS/Vault/HSM/tokenisation. The core ships a JDK-only
+// reference (AES-256-GCM, random 12-byte IV prepended, Base64) so it pulls no crypto dep (GR-7).
+Cipher cipher = new AesGcmCipher(key); // key is 16/24/32 bytes; the caller owns it
+
+Map<String, Object> schema = provider.schemaFor(env.job());  // the same per-URN schema you validate against
+if (schema != null) {
+    // Producer — validate CLEARTEXT first, then encrypt the marked leaves in place:
+    SchemaValidation.validate(provider, env.job(), env.data());
+    Gdpr.protect(env.data(), schema, cipher);
+}
+String body = EnvelopeCodec.encode(env);                     // ciphertext rides inside data
+
+// Consumer — decrypt the marked leaves in place AFTER decode, BEFORE the handler reads data:
+Envelope in = EnvelopeCodec.decode(body);
+Map<String, Object> inSchema = provider.schemaFor(in.job());
+if (inSchema != null) {
+    Gdpr.unprotect(in.data(), inSchema, cipher);             // wrong key → DecryptException (retry/DLQ)
+}
+```
+
+The wire envelope stays **frozen** (GR-1): only the **value** of a sensitive field changes
+— it becomes a ciphertext **string**, so `data` is still pure JSON (GR-3) and any SDK can
+carry the envelope even without the key. `meta.schema_version` stays `1` and `trace_id` is
+untouched (GR-4). Each leaf is canonically JSON-encoded before encryption and decoded back
+after, so `protect` → `unprotect` restores the value **byte-for-byte** (a number comes back a
+number, an object an object). The sensitive paths come from the schema's `x-gdpr-sensitive`
+marks (`SensitivePaths.of(schema)` — nested objects, array items `field[]`, and the root),
+which are **validation-neutral** so annotating a schema is never a breaking change. Validate
+cleartext **before** `protect` / **after** `unprotect`: a schema that constrains a sensitive
+field (`minLength`, `enum`, …) would reject the ciphertext string otherwise.
+
 ## What this core is (and isn't)
 
 It enforces the **contract**: the envelope shape, URN identity, trace propagation,

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>com.babelqueue</groupId>
     <artifactId>babelqueue-core</artifactId>
-    <version>1.6.0</version>
+    <version>1.7.0</version>
     <packaging>jar</packaging>
 
     <name>BabelQueue Core</name>

src/main/java/com/babelqueue/JsonValues.java

@@ -0,0 +1,46 @@
+package com.babelqueue;
+
+/**
+ * Canonical encode/decode for a <b>single</b> decoded-JSON value, using the same minimal codec
+ * the wire envelope uses. It is the seam field-level features ({@link com.babelqueue.gdpr})
+ * need: the core's {@link Json} reader/writer is package-private (it must never force a JSON
+ * library on consumers, GR-7), so this class exposes just enough of it — one value in, one value
+ * out — without widening {@code Json} itself.
+ *
+ * <p>Because it routes through the very same codec, the round-trip is <b>type-exact</b>: a value
+ * decoded by {@link EnvelopeCodec#decode} (numbers as {@link Long}/{@link java.math.BigInteger}/
+ * {@link Double}, objects as {@link java.util.LinkedHashMap}, arrays as {@link java.util.ArrayList})
+ * re-encodes and re-decodes back to the same Java types. That is what lets
+ * {@link com.babelqueue.gdpr.Gdpr#protect protect}/{@link com.babelqueue.gdpr.Gdpr#unprotect unprotect}
+ * restore a protected field byte-for-byte after a decrypt.
+ */
+public final class JsonValues {
+
+    private JsonValues() {
+    }
+
+    /**
+     * Encode one decoded-JSON value to its compact canonical JSON string — the same form the
+     * envelope codec emits (slashes and non-ASCII left literal, no insignificant whitespace).
+     *
+     * @param value a decoded-JSON value ({@code Map}/{@code List}/{@code String}/{@code Number}/
+     *              {@code Boolean}/{@code null})
+     * @return the compact JSON encoding
+     * @throws BabelQueueException if the value cannot be encoded (e.g. a non-finite number)
+     */
+    public static String encode(Object value) {
+        return Json.write(value);
+    }
+
+    /**
+     * Parse one JSON document back into a decoded-JSON value, with the same types the envelope
+     * codec produces. The exact inverse of {@link #encode(Object)}.
+     *
+     * @param raw a JSON document holding a single value
+     * @return the decoded value
+     * @throws BabelQueueException if {@code raw} is not a single, well-formed JSON value
+     */
+    public static Object decode(String raw) {
+        return Json.parse(raw);
+    }
+}

src/main/java/com/babelqueue/gdpr/AesGcmCipher.java

@@ -0,0 +1,101 @@
+package com.babelqueue.gdpr;
+
+import java.nio.charset.StandardCharsets;
+import java.security.GeneralSecurityException;
+import java.security.SecureRandom;
+import java.util.Arrays;
+import java.util.Base64;
+import javax.crypto.spec.GCMParameterSpec;
+import javax.crypto.spec.SecretKeySpec;
+
+/**
+ * A reference {@link Cipher} built ONLY on the JDK's {@code javax.crypto} ({@code AES/GCM/NoPadding}):
+ * AES-GCM authenticated encryption with a fresh random 12-byte IV per call, the IV <b>prepended</b>
+ * to the ciphertext, the whole thing Base64-encoded so it drops straight into a JSON string. The key
+ * is the CALLER's — this type performs no key management, rotation or derivation; bind a KMS-backed
+ * {@link Cipher} for that.
+ *
+ * <p>A 32-byte key selects AES-256-GCM (recommended); 24- and 16-byte keys select AES-192/128-GCM.
+ * GCM authenticates the ciphertext, so {@link #decrypt} rejects any tampered or wrong-key input by
+ * throwing (it never returns corrupt plaintext). It pulls no third-party crypto dependency (GR-7)
+ * and is safe for concurrent use — {@code javax.crypto.Cipher} instances are created per call, and
+ * the stored key material is only read.
+ */
+public final class AesGcmCipher implements Cipher {
+
+    /** AES-GCM standard nonce/IV length, in bytes. A 12-byte IV is the recommended GCM size. */
+    private static final int IV_LENGTH = 12;
+
+    /** GCM authentication-tag length, in bits (the full 128-bit tag). */
+    private static final int TAG_BITS = 128;
+
+    private static final String TRANSFORMATION = "AES/GCM/NoPadding";
+    private static final String ALGORITHM = "AES";
+
+    private final SecretKeySpec key;
+    private final SecureRandom random = new SecureRandom();
+
+    /**
+     * Build an AES-GCM reference cipher from a raw symmetric key. The key length selects the AES
+     * variant: 32 bytes &rarr; AES-256-GCM (recommended), 24 &rarr; AES-192, 16 &rarr; AES-128.
+     *
+     * @param keyBytes the raw symmetric key (16, 24, or 32 bytes)
+     * @throws InvalidKeySizeException if the key is not 16, 24, or 32 bytes
+     */
+    public AesGcmCipher(byte[] keyBytes) {
+        int len = keyBytes == null ? 0 : keyBytes.length;
+        if (len != 16 && len != 24 && len != 32) {
+            throw new InvalidKeySizeException(len);
+        }
+        this.key = new SecretKeySpec(keyBytes, ALGORITHM);
+    }
+
+    /**
+     * Seals {@code plaintext} with a fresh random IV, prepends the IV, and Base64-encodes the result
+     * ({@code Base64(iv || ciphertext || tag)}).
+     */
+    @Override
+    public String encrypt(byte[] plaintext) throws GeneralSecurityException {
+        byte[] iv = new byte[IV_LENGTH];
+        random.nextBytes(iv);
+
+        javax.crypto.Cipher gcm = javax.crypto.Cipher.getInstance(TRANSFORMATION);
+        gcm.init(javax.crypto.Cipher.ENCRYPT_MODE, key, new GCMParameterSpec(TAG_BITS, iv));
+        byte[] sealed = gcm.doFinal(plaintext);
+
+        byte[] out = new byte[iv.length + sealed.length];
+        System.arraycopy(iv, 0, out, 0, iv.length);
+        System.arraycopy(sealed, 0, out, iv.length, sealed.length);
+        return Base64.getEncoder().encodeToString(out);
+    }
+
+    /**
+     * Reverses {@link #encrypt}: Base64-decodes, splits off the prepended IV, and opens the GCM
+     * ciphertext. A wrong key or tampered input fails GCM authentication and throws (never corrupt
+     * plaintext).
+     *
+     * @throws MalformedCiphertextException if the input is not valid Base64 or is too short to hold
+     *                                      an IV (i.e. not something this cipher produced)
+     * @throws GeneralSecurityException     if GCM authentication fails (wrong key or tampering)
+     */
+    @Override
+    public byte[] decrypt(String ciphertext) throws GeneralSecurityException {
+        byte[] raw;
+        try {
+            raw = Base64.getDecoder().decode(ciphertext.getBytes(StandardCharsets.UTF_8));
+        } catch (IllegalArgumentException ex) {
+            throw new MalformedCiphertextException("not valid Base64", ex);
+        }
+        if (raw.length < IV_LENGTH) {
+            throw new MalformedCiphertextException("shorter than the IV", null);
+        }
+
+        byte[] iv = Arrays.copyOfRange(raw, 0, IV_LENGTH);
+        byte[] sealed = Arrays.copyOfRange(raw, IV_LENGTH, raw.length);
+
+        javax.crypto.Cipher gcm = javax.crypto.Cipher.getInstance(TRANSFORMATION);
+        gcm.init(javax.crypto.Cipher.DECRYPT_MODE, key, new GCMParameterSpec(TAG_BITS, iv));
+        // AEADBadTagException (a GeneralSecurityException) on wrong key / tampered input.
+        return gcm.doFinal(sealed);
+    }
+}

src/main/java/com/babelqueue/gdpr/Cipher.java

@@ -0,0 +1,48 @@
+package com.babelqueue.gdpr;
+
+/**
+ * The field-level protection primitive that the <b>caller provides</b> — a seam onto a KMS, a
+ * Vault transit engine, an HSM, a tokenisation service, or the reference {@link AesGcmCipher}
+ * below. {@link Gdpr#protect protect} runs {@link #encrypt} over every {@code x-gdpr-sensitive}
+ * leaf's value (after it is canonically JSON-encoded); {@link Gdpr#unprotect unprotect} runs
+ * {@link #decrypt} to restore it. Keeping this an interface is what holds GR-7: the core never
+ * pulls a crypto/KMS dependency — only a caller who binds a concrete backend does.
+ *
+ * <p>Contract for an implementation:
+ * <ul>
+ *   <li>{@link #encrypt} takes the canonical JSON bytes of one field value (see
+ *       {@link Gdpr#protect}) and returns the ciphertext as a <b>String</b> that is valid for
+ *       placement inside a JSON document (the {@link AesGcmCipher} reference returns Base64, which
+ *       is). The same plaintext MAY encrypt to a different string each call — a random nonce/IV is
+ *       expected and good.</li>
+ *   <li>{@link #decrypt} is the exact inverse: given a string {@code encrypt} produced, it returns
+ *       the original JSON bytes <b>byte-for-byte</b>. A string it did not produce, or one produced
+ *       under a different key, MUST throw rather than return silent garbage, so a wrong-key consume
+ *       fails loudly (the message then takes retry / dead-letter).</li>
+ *   <li>Both MUST be safe for concurrent use; a producer/consumer fans the same {@code Cipher}
+ *       across threads.</li>
+ * </ul>
+ */
+public interface Cipher {
+
+    /**
+     * Protects one field value (its canonical JSON bytes) and returns a JSON-safe ciphertext
+     * string.
+     *
+     * @param plaintext the canonical JSON bytes of one field value
+     * @return the ciphertext, encoded so it is safe to place inside a JSON string
+     * @throws Exception if encryption fails (surfaced wrapped by {@link Gdpr#protect})
+     */
+    String encrypt(byte[] plaintext) throws Exception;
+
+    /**
+     * Reverses {@link #encrypt}, returning the original field-value JSON bytes.
+     *
+     * @param ciphertext a string produced by {@link #encrypt}
+     * @return the original field-value JSON bytes
+     * @throws Exception if the input is not a valid ciphertext, is tampered, or was produced under
+     *                   a different key (surfaced as {@link DecryptException} by
+     *                   {@link Gdpr#unprotect})
+     */
+    byte[] decrypt(String ciphertext) throws Exception;
+}

src/main/java/com/babelqueue/gdpr/DecryptException.java

@@ -0,0 +1,28 @@
+package com.babelqueue.gdpr;
+
+import com.babelqueue.BabelQueueException;
+
+/**
+ * Raised by {@link Gdpr#unprotect} when a protected field cannot be restored on the consume side —
+ * a wrong key, a tampered/garbled ciphertext, or a value that is not the string {@link Gdpr#protect}
+ * produced. {@code unprotect} stops at the first such failure and throws this, so it is
+ * distinguishable from a missing field (which is skipped, not an error) and from an already-cleartext
+ * non-string leaf (which is left untouched).
+ *
+ * <p>A consumer should treat it as fatal for that message: fail the delivery so the adapter retries
+ * and eventually dead-letters it, rather than handle unreadable PII. It is unchecked
+ * ({@link BabelQueueException} is a {@link RuntimeException}) so it composes with the existing
+ * handler/redrive flow that already reacts to thrown runtime exceptions.
+ */
+public class DecryptException extends BabelQueueException {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * @param message the failure detail
+     * @param cause   the underlying cipher or decode failure
+     */
+    public DecryptException(String message, Throwable cause) {
+        super("babelqueue/gdpr: cannot decrypt a protected field: " + message, cause);
+    }
+}