feat(guardrails): vault-backed Presidio encryption keys (pure layer)

Secret-backed half of the advanced-anonymizers gap. Key material must never sit
in the policy row (the module's own comment flagged this), but naively stripping
it was a TRAP: normalize() silently downgraded a keyless encrypt spec to
'replace', so encryption would vanish on the persist→read round-trip.

Fix: a KEYLESS encrypt spec is now the legal PRODUCTION shape meaning 'use the
org's vaulted key'. validateOperatorSpec accepts it (a wrong-LENGTH inline key is
still a hard error), so the intent survives persistence with no key material.
New pure helpers: PRESIDIO_ENCRYPT_KEY_SECRET, policyUsesEncrypt,
stripInlineEncryptKeys (what we persist), bindEncryptKey (binds the vaulted key
at call time). FAIL SAFE: an unresolvable key DOWNGRADES to replace — the value
is still masked, never plaintext — and the affected entities are reported, not
hidden. A guard test proves an empty-key encrypt can never reach Presidio.

6 new unit tests (24/24 green); 2 existing assertions updated to the new,
deliberate semantics.

Author: alichherawalla

src/lib/presidio-anonymizers.ts

@@ -134,8 +134,12 @@ export function validateOperatorSpec(draft: unknown): OperatorValidation {
     }
 
     case 'encrypt': {
+      // A KEYLESS encrypt spec is legal and is the PRODUCTION shape: it means "use the org's
+      // vault-held key", bound at call time by bindEncryptKey. Key material is therefore never
+      // persisted in the policy row. An INLINE key is still accepted (bootstrap/tests) but must be a
+      // real AES length; a wrong-length key is rejected rather than silently downgraded.
       const key = typeof d.key === 'string' ? d.key : '';
-      if (!key) return { ok: false, error: 'encrypt requires a key' };
+      if (!key) return { ok: true, value: { type: 'encrypt' } };
       const bytes = byteLength(key);
       if (!(VALID_ENCRYPT_KEY_BYTES as readonly number[]).includes(bytes)) {
         return {
@@ -360,3 +364,57 @@ export function describeOperator(spec: OperatorSpec): string {
       return 'replace';
   }
 }
+
+// ─── Vault-backed encryption keys (the secret-backed half of advanced anonymizers) ────────────────
+// The rule: an AES key is SECRET MATERIAL and must never sit in the policy row. So the persisted
+// policy carries the encrypt INTENT only (a keyless encrypt spec) and the key is resolved from the
+// secrets store at call time. These are PURE so the whole rule is unit-testable with zero I/O.
+
+/** Where the org's Presidio AES key lives in the secrets store (mirrors the Slack webhook pattern). */
+export const PRESIDIO_ENCRYPT_KEY_SECRET = 'org/presidio_encrypt_key';
+
+/** Does this policy encrypt anywhere (⇒ a key must be resolved before it can run)? PURE. */
+export function policyUsesEncrypt(policy: AnonymizerPolicy): boolean {
+  if (policy.default.type === 'encrypt') return true;
+  return Object.values(policy.perEntity).some((spec) => spec.type === 'encrypt');
+}
+
+/**
+ * Drop inline AES key material from every encrypt spec — the shape we PERSIST. PURE. The encrypt
+ * intent survives (a keyless encrypt spec is valid and means "use the vaulted key"), so stripping the
+ * key can never silently disable encryption.
+ */
+export function stripInlineEncryptKeys(policy: AnonymizerPolicy): AnonymizerPolicy {
+  const strip = (spec: OperatorSpec): OperatorSpec =>
+    spec.type === 'encrypt' && spec.key !== undefined ? { type: 'encrypt' } : spec;
+  const perEntity: Record<string, OperatorSpec> = {};
+  for (const [entity, spec] of Object.entries(policy.perEntity)) perEntity[entity] = strip(spec);
+  return { default: strip(policy.default), perEntity };
+}
+
+/**
+ * Bind the vaulted key into every encrypt spec, ready to send to Presidio. PURE.
+ *
+ * FAIL SAFE, never fail open: when no key can be resolved, an encrypt spec is DOWNGRADED to `replace`
+ * (the value is still masked — it is never emitted in plaintext) and the affected entity is reported
+ * in `downgraded` so the caller can surface the degradation honestly instead of hiding it. A spec that
+ * already carries an inline key keeps it (bootstrap/tests).
+ */
+export function bindEncryptKey(
+  policy: AnonymizerPolicy,
+  key: string | null,
+): { policy: AnonymizerPolicy; downgraded: string[] } {
+  const downgraded: string[] = [];
+  const bind = (spec: OperatorSpec, label: string): OperatorSpec => {
+    if (spec.type !== 'encrypt') return spec;
+    if (spec.key) return spec;
+    if (key) return { type: 'encrypt', key };
+    downgraded.push(label);
+    return { type: 'replace' };
+  };
+  const perEntity: Record<string, OperatorSpec> = {};
+  for (const [entity, spec] of Object.entries(policy.perEntity)) {
+    perEntity[entity] = bind(spec, entity);
+  }
+  return { policy: { default: bind(policy.default, 'DEFAULT'), perEntity }, downgraded };
+}

test/presidio-anonymizers.test.ts

@@ -1,6 +1,9 @@
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import {
+  bindEncryptKey,
+  policyUsesEncrypt,
+  stripInlineEncryptKeys,
   ANONYMIZE_OPERATORS,
   buildAnonymizeRequest,
   byteLength,
@@ -118,9 +121,11 @@ test('validateOperatorSpec rejects bad operator + bad encrypt keys', () => {
   assert.equal(validateOperatorSpec(null).ok, false);
   assert.equal(validateOperatorSpec('string').ok, false);
 
+  // A KEYLESS encrypt spec is now the PRODUCTION shape — it means "use the org's vaulted key", so the
+  // policy row never carries key material. It validates, carrying the intent with no key.
   const noKey = validateOperatorSpec({ type: 'encrypt' });
-  assert.equal(noKey.ok, false);
-  assert.match((noKey as { error: string }).error, /requires a key/);
+  assert.equal(noKey.ok, true);
+  assert.deepEqual((noKey as { value: unknown }).value, { type: 'encrypt' });
 
   const shortKey = validateOperatorSpec({ type: 'encrypt', key: 'short' });
   assert.equal(shortKey.ok, false);
@@ -161,7 +166,8 @@ test('validateAnonymizerPolicy: missing default uses safe fallback; empty is val
 });
 
 test('validateAnonymizerPolicy: bad default operator is a hard error', () => {
-  const res = validateAnonymizerPolicy({ default: { type: 'encrypt' } });
+  // A wrong-LENGTH inline key is still a hard error (a keyless encrypt is legal — vault-backed).
+  const res = validateAnonymizerPolicy({ default: { type: 'encrypt', key: 'too-short' } });
   assert.equal(res.ok, false);
   assert.match((res as { error: string }).error, /default operator/);
 });
@@ -325,3 +331,73 @@ test('operator + hash catalogs match the verified live engine contract', () => {
   // The shipped BFSI default policy is itself valid.
   assert.equal(validateAnonymizerPolicy(DEFAULT_ANONYMIZER_POLICY).ok, true);
 });
+
+// ─── Vault-backed encryption keys ─────────────────────────────────────────────────────────────────
+// The rule: key material never lives in the policy row. The persisted policy carries the encrypt
+// INTENT (keyless spec); the key is bound from the secrets store at call time; an unresolvable key
+// DOWNGRADES to replace (still masked — never plaintext) and is reported, never hidden.
+
+test('policyUsesEncrypt detects encryption in the default or any per-entity spec', () => {
+  assert.equal(policyUsesEncrypt({ default: { type: 'replace' }, perEntity: {} }), false);
+  assert.equal(policyUsesEncrypt({ default: { type: 'encrypt' }, perEntity: {} }), true);
+  assert.equal(
+    policyUsesEncrypt({ default: { type: 'replace' }, perEntity: { IN_PAN: { type: 'encrypt' } } }),
+    true,
+  );
+});
+
+test('stripInlineEncryptKeys removes key material but PRESERVES the encrypt intent', () => {
+  const key = 'k'.repeat(32);
+  const stripped = stripInlineEncryptKeys({
+    default: { type: 'encrypt', key },
+    perEntity: { IN_PAN: { type: 'encrypt', key }, EMAIL_ADDRESS: { type: 'mask', charsToMask: 4 } },
+  });
+  assert.deepEqual(stripped.default, { type: 'encrypt' }, 'default keeps encrypt, loses the key');
+  assert.deepEqual(stripped.perEntity.IN_PAN, { type: 'encrypt' });
+  assert.equal(stripped.perEntity.EMAIL_ADDRESS.charsToMask, 4, 'other operators untouched');
+  // The stripped shape must survive a persist→read round-trip as ENCRYPT (not silently downgraded).
+  assert.equal(normalizeAnonymizerPolicy(stripped).perEntity.IN_PAN.type, 'encrypt');
+});
+
+test('bindEncryptKey injects the vaulted key into every keyless encrypt spec', () => {
+  const key = 'v'.repeat(24);
+  const { policy, downgraded } = bindEncryptKey(
+    { default: { type: 'encrypt' }, perEntity: { IN_PAN: { type: 'encrypt' }, X: { type: 'redact' } } },
+    key,
+  );
+  assert.deepEqual(policy.default, { type: 'encrypt', key });
+  assert.deepEqual(policy.perEntity.IN_PAN, { type: 'encrypt', key });
+  assert.deepEqual(policy.perEntity.X, { type: 'redact' }, 'non-encrypt specs pass through');
+  assert.deepEqual(downgraded, [], 'nothing degraded when the key resolves');
+});
+
+test('bindEncryptKey FAILS SAFE: no key ⇒ downgrade to replace (masked, never plaintext) + report', () => {
+  const { policy, downgraded } = bindEncryptKey(
+    { default: { type: 'replace' }, perEntity: { IN_PAN: { type: 'encrypt' }, AADHAAR: { type: 'encrypt' } } },
+    null,
+  );
+  assert.deepEqual(policy.perEntity.IN_PAN, { type: 'replace' }, 'still masked, not passed through');
+  assert.deepEqual(policy.perEntity.AADHAAR, { type: 'replace' });
+  assert.deepEqual(downgraded.sort(), ['AADHAAR', 'IN_PAN'], 'the degradation is reported honestly');
+  // and the produced Presidio operator config is a real masking operator, never an empty-key encrypt
+  assert.deepEqual(specToOperatorConfig(policy.perEntity.IN_PAN), { type: 'replace' });
+});
+
+test('bindEncryptKey keeps an inline key (bootstrap) in preference to the vaulted one', () => {
+  const inline = 'i'.repeat(16);
+  const { policy, downgraded } = bindEncryptKey(
+    { default: { type: 'encrypt', key: inline }, perEntity: {} },
+    'v'.repeat(32),
+  );
+  assert.deepEqual(policy.default, { type: 'encrypt', key: inline });
+  assert.deepEqual(downgraded, []);
+});
+
+test('a keyless encrypt policy never reaches Presidio with an empty key', () => {
+  // The regression this guards: specToOperatorConfig({type:'encrypt'}) yields key:'' which Presidio
+  // rejects; bindEncryptKey must resolve or downgrade FIRST, so an empty key can never be sent.
+  const { policy } = bindEncryptKey({ default: { type: 'encrypt' }, perEntity: {} }, null);
+  const built = buildAnonymizeRequest('x', [{ entity_type: 'IN_PAN', start: 0, end: 1, score: 1 }], policy);
+  assert.notDeepEqual(built.anonymizers.DEFAULT, { type: 'encrypt', key: '' });
+  assert.deepEqual(built.anonymizers.DEFAULT, { type: 'replace' });
+});