feat(guardrails): the operator's masking policy now governs PRODUCTION redaction

Closes the advanced-anonymizers gap. The defect: an operator could configure
per-entity operators (mask/redact/hash/encrypt/keep) and the ADMIN TEST box
honoured them, but production redaction (getPii().scan -> scanWithPresidio) sent a
hard-coded single 'replace' for every entity — so the configured policy never
governed real runs. Same class as 'verify the real path, not the proxy'.

- adapters/presidio.ts: loadPolicy now also loads the org operator policy and,
  only when the policy actually encrypts, binds the vaulted AES key; the
  /anonymize body is built by the SAME pure buildAnonymizeRequest the test
  surface uses (DRY — one shaping authority). Absent policy => legacy replace, so
  every existing caller is byte-identical.
- policy store: strips inline key material before persisting (intent survives).
- New admin route .../masking/encrypt-key: GET reports only whether a key exists;
  POST generates one server-side (CSPRNG) straight into the secrets store and
  NEVER returns it; DELETE removes it. Audited create/rotate/remove.
- UI: the plaintext AES-key input is gone (it persisted a secret); replaced by an
  EncryptionKeyPanel showing configured/not-set + Generate/Rotate, and an honest
  note that without a key encrypt degrades to masking.

5 integration tests assert the real /anonymize wire body (legacy replace,
configured operators, bound encrypt key, fail-safe downgrade, anonymizer-down
fallback still redacts). Suite 5069 pass / 0 fail; coverage:check green.

Author: alichherawalla

src/app/api/v1/admin/governance/masking/encrypt-key/route.ts

@@ -0,0 +1,91 @@
+import { randomBytes } from 'node:crypto';
+import { NextResponse } from 'next/server';
+import { auditFromSession } from '@/lib/audit-actor';
+import { requireAdmin } from '@/lib/authz';
+import { PRESIDIO_ENCRYPT_KEY_SECRET } from '@/lib/presidio-anonymizers';
+import { currentOrgId } from '@/lib/tenancy';
+
+export const dynamic = 'force-dynamic';
+
+// Lifecycle of the org's Presidio AES key for the `encrypt` anonymizer operator.
+//
+// The key is SECRET MATERIAL: it is generated HERE (server-side CSPRNG), written straight to the
+// secrets store, and NEVER returned by any endpoint, echoed to a client, or written to a file — the
+// operator only ever learns *whether* a key is configured. This is what makes a keyless `encrypt`
+// policy spec safe to persist: the intent lives in the policy row, the key lives only in the vault.
+//
+// A 24-byte CSPRNG value base64-encodes to 32 ASCII characters = a valid AES-256 key length (Presidio
+// accepts 16/24/32 BYTES).
+function generateAesKey(): string {
+  return randomBytes(24).toString('base64');
+}
+
+async function secrets() {
+  const { openBaoSecrets } = await import('@/lib/adapters/secrets');
+  return openBaoSecrets;
+}
+
+/** Is a key resolvable (vault first, env bootstrap second)? Never reveals the value. */
+async function keyConfigured(): Promise<boolean> {
+  try {
+    const vaulted = await (await secrets()).get(PRESIDIO_ENCRYPT_KEY_SECRET);
+    if (typeof vaulted === 'string' && vaulted.trim()) return true;
+  } catch {
+    /* vault unreachable — fall through to the env bootstrap */
+  }
+  return Boolean(process.env.OFFGRID_PRESIDIO_ENCRYPT_KEY?.trim());
+}
+
+export async function GET(req: Request) {
+  const gate = await requireAdmin(req);
+  if (gate instanceof NextResponse) return gate;
+  return NextResponse.json({
+    configured: await keyConfigured(),
+    note: 'The AES key is generated server-side and held in the secrets store. It is never returned. Without a key, an encrypt operator degrades to masking (the value is still redacted, never plaintext).',
+  });
+}
+
+/** Generate (or rotate) the key. Returns only whether one is now configured — never the material. */
+export async function POST(req: Request) {
+  const gate = await requireAdmin(req);
+  if (gate instanceof NextResponse) return gate;
+  const orgId = await currentOrgId();
+  const store = await secrets();
+  if (!store.set) {
+    return NextResponse.json({ error: 'secrets backend is not writable' }, { status: 503 });
+  }
+  const rotated = await keyConfigured();
+  try {
+    await store.set(PRESIDIO_ENCRYPT_KEY_SECRET, generateAesKey());
+  } catch (e) {
+    return NextResponse.json(
+      { error: `could not store the key: ${(e as Error).message}` },
+      { status: 502 },
+    );
+  }
+  auditFromSession(gate, orgId, {
+    action: rotated ? 'governance.masking.encrypt-key.rotate' : 'governance.masking.encrypt-key.create',
+    resource: `secret:${PRESIDIO_ENCRYPT_KEY_SECRET}`,
+    outcome: 'ok',
+  });
+  return NextResponse.json({ ok: true, configured: true, rotated });
+}
+
+/** Remove the key. Encryption then degrades to masking (fail safe), which the surface reports. */
+export async function DELETE(req: Request) {
+  const gate = await requireAdmin(req);
+  if (gate instanceof NextResponse) return gate;
+  const orgId = await currentOrgId();
+  try {
+    const store = await secrets();
+    if (store.remove) await store.remove(PRESIDIO_ENCRYPT_KEY_SECRET);
+  } catch {
+    /* best-effort */
+  }
+  auditFromSession(gate, orgId, {
+    action: 'governance.masking.encrypt-key.remove',
+    resource: `secret:${PRESIDIO_ENCRYPT_KEY_SECRET}`,
+    outcome: 'ok',
+  });
+  return NextResponse.json({ ok: true, configured: await keyConfigured() });
+}

src/components/guardrails/PresidioAnonymizers.tsx

@@ -2,7 +2,7 @@
 
 import { Plus, Trash } from '@phosphor-icons/react/dist/ssr';
 import { useRouter } from 'next/navigation';
-import { useId, useState } from 'react';
+import { useEffect, useId, useState } from 'react';
 import { toast } from 'sonner';
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
@@ -27,6 +27,7 @@ import {
   HASH_TYPES,
   type HashType,
   type OperatorSpec,
+  policyUsesEncrypt,
 } from '@/lib/presidio-anonymizers';
 
 // Per-entity anonymizer OPERATOR policy editor + a live test box. This is the "how do we mask each
@@ -254,6 +255,7 @@ export function PresidioAnonymizers({
         </div>
 
         {/* Image redaction — the real upload → redact → review surface */}
+        <EncryptionKeyPanel usesEncrypt={policyUsesEncrypt(policy)} />
         <ImageRedactionPanel available={imageRedactionAvailable} />
       </div>
     </div>
@@ -287,7 +289,8 @@ function OperatorEditor({
         onChange({ type, hashType: 'sha256' });
         break;
       case 'encrypt':
-        onChange({ type, key: '' });
+        // No inline key: a keyless encrypt spec means "use the org's vaulted key".
+        onChange({ type });
         break;
       case 'replace':
         onChange({ type, newValue: '' });
@@ -374,15 +377,77 @@ function OperatorEditor({
       ) : null}
 
       {spec.type === 'encrypt' ? (
-        <Input
-          value={spec.key ?? ''}
-          placeholder="AES key (16 / 24 / 32 chars)"
-          className="font-mono"
-          onChange={(e) => onChange({ type: 'encrypt', key: e.target.value })}
-        />
+        // The AES key is NEVER typed or stored here — it is generated into the secrets store and
+        // bound at scan time. Manage it with "Encryption key" below.
+        <p className="rounded border border-dashed border-border px-2 py-1.5 text-[11px] text-muted-foreground">
+          Uses the organization&rsquo;s encryption key from the secrets store. Manage it under
+          <span className="text-foreground"> Encryption key</span> below.
+        </p>
       ) : null}
 
       <p className="text-[11px] text-muted-foreground">{describeOperator(spec)}</p>
     </div>
   );
 }
+
+// ─── Encryption key — the vault-backed AES key for the `encrypt` operator ─────────────────────────
+// The key is generated server-side into the secrets store and NEVER returned, so this panel only ever
+// shows whether one is configured. Without a key an encrypt operator degrades to masking (the value is
+// still redacted, never plaintext) — stated plainly rather than failing silently.
+function EncryptionKeyPanel({ usesEncrypt }: Readonly<{ usesEncrypt: boolean }>) {
+  const [configured, setConfigured] = useState<boolean | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => {
+    let live = true;
+    fetch('/api/v1/admin/governance/masking/encrypt-key')
+      .then((r) => (r.ok ? r.json() : null))
+      .then((j) => {
+        if (live) setConfigured(j ? Boolean(j.configured) : null);
+      })
+      .catch(() => {
+        if (live) setConfigured(null);
+      });
+    return () => {
+      live = false;
+    };
+  }, []);
+
+  async function generate(): Promise<void> {
+    setBusy(true);
+    try {
+      const res = await fetch('/api/v1/admin/governance/masking/encrypt-key', { method: 'POST' });
+      const body = (await res.json().catch(() => ({}))) as { configured?: boolean; rotated?: boolean; error?: string };
+      if (!res.ok) {
+        toast.error(body.error ?? 'Could not store the key');
+        return;
+      }
+      setConfigured(Boolean(body.configured));
+      toast.success(body.rotated ? 'Encryption key rotated' : 'Encryption key generated');
+    } catch {
+      toast.error('Could not reach the secrets store');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div className="space-y-2 rounded-md border border-border p-4">
+      <div className="flex flex-wrap items-center gap-2">
+        <span className="text-sm font-medium">Encryption key</span>
+        <Badge variant={configured ? 'default' : 'secondary'}>
+          {configured === null ? 'unknown' : configured ? 'configured' : 'not set'}
+        </Badge>
+        <Button type="button" size="sm" variant="outline" className="ml-auto" onClick={generate} disabled={busy}>
+          {busy ? 'Working…' : configured ? 'Rotate key' : 'Generate key'}
+        </Button>
+      </div>
+      <p className="text-xs text-muted-foreground">
+        Generated on the server and held in the secrets store — it is never displayed or downloadable.
+        {usesEncrypt && configured === false
+          ? ' Your policy encrypts an entity but no key is set, so those values are masked instead until you generate one.'
+          : ' Required only by the encrypt operator; without it, encrypt degrades to masking.'}
+      </p>
+    </div>
+  );
+}

src/lib/adapters/presidio.ts

@@ -5,6 +5,13 @@ import {
   type NormalizedRecognizer,
   type ThresholdConfig,
 } from '@/lib/presidio-recognizers';
+import {
+  type AnonymizerPolicy,
+  bindEncryptKey,
+  buildAnonymizeRequest,
+  PRESIDIO_ENCRYPT_KEY_SECRET,
+  policyUsesEncrypt,
+} from '@/lib/presidio-anonymizers';
 import { regexScan } from './pii-regex';
 import type { PiiPort, PiiResult } from './types';
 
@@ -21,6 +28,14 @@ export interface PresidioScanPolicy {
   recognizers?: NormalizedRecognizer[];
   thresholds?: ThresholdConfig;
   language?: string;
+  /**
+   * The org's per-entity OPERATOR policy (mask / redact / hash / encrypt / keep). ABSENT ⇒ the legacy
+   * single-`replace` behaviour, so every existing caller is unchanged. PRESENT ⇒ the operator's
+   * configured operators actually govern production redaction (they previously only applied on the
+   * admin test surface, which is the gap this closes). Encrypt keys are already BOUND here (the
+   * caller resolves them from the vault via bindEncryptKey) — this layer never touches secrets.
+   */
+  operators?: AnonymizerPolicy;
 }
 
 interface PresidioEntity {
@@ -152,9 +167,15 @@ export async function scanWithPresidio(
     }
 
     try {
+      // The org's OPERATOR policy governs production redaction when present (reusing the SAME pure
+      // request builder the admin test surface uses — one authority, no second shaping rule); absent,
+      // the legacy single-`replace` body is sent verbatim.
+      const body = policy.operators
+        ? buildAnonymizeRequest(text, entities, policy.operators)
+        : { text, analyzer_results: entities, anonymizers: anonymizers(entities) };
       const anonymized = (await postJson(
         `${config.anonymizerUrl}/anonymize`,
-        { text, analyzer_results: entities, anonymizers: anonymizers(entities) },
+        body,
         config.timeoutMs,
         fetcher,
       )) as { text?: unknown };
@@ -197,18 +218,41 @@ export async function scanWithPresidio(
   }
 }
 
+/**
+ * Resolve the org's AES key for the `encrypt` operator from the SECRETS STORE (OpenBao), with an env
+ * bootstrap fallback. Never throws and never logs the material — an unresolved key makes
+ * bindEncryptKey downgrade encryption to masking rather than fail open.
+ */
+async function resolveEncryptKey(): Promise<string | null> {
+  try {
+    const { openBaoSecrets } = await import('@/lib/adapters/secrets');
+    const vaulted = await openBaoSecrets.get(PRESIDIO_ENCRYPT_KEY_SECRET);
+    if (typeof vaulted === 'string' && vaulted.trim()) return vaulted.trim();
+  } catch {
+    /* vault unreachable — fall through to the env bootstrap */
+  }
+  return process.env.OFFGRID_PRESIDIO_ENCRYPT_KEY?.trim() || null;
+}
+
 async function loadPolicy(orgId?: string): Promise<PresidioScanPolicy> {
   try {
     const { getThresholds, listRecognizers } = await import('@/lib/presidio-recognizers');
+    const { getAnonymizerPolicy } = await import('@/lib/presidio-anonymizer-policy-store');
     const resolvedOrg = orgId?.trim() || 'default';
-    const [recognizers, thresholds] = await Promise.all([
+    const [recognizers, thresholds, stored] = await Promise.all([
       listRecognizers(resolvedOrg),
       getThresholds(resolvedOrg),
+      getAnonymizerPolicy(resolvedOrg),
     ]);
-    return { recognizers, thresholds };
+    // Bind the vaulted key ONLY when the policy actually encrypts, so a non-encrypting org never
+    // touches the secrets store. An unresolvable key downgrades to masking (fail safe, reported).
+    const operators = policyUsesEncrypt(stored)
+      ? bindEncryptKey(stored, await resolveEncryptKey()).policy
+      : stored;
+    return { recognizers, thresholds, operators };
   } catch {
     // The default India recognizers are folded in by buildAnalyzeRequest. A policy-store failure must
-    // not bypass redaction; it only loses the org overrides for this call.
+    // not bypass redaction; it only loses the org overrides for this call (legacy replace applies).
     return {};
   }
 }

src/lib/presidio-anonymizer-policy-store.ts

@@ -9,6 +9,7 @@ import {
   type AnonymizerPolicy,
   DEFAULT_ANONYMIZER_POLICY,
   normalizeAnonymizerPolicy,
+  stripInlineEncryptKeys,
 } from '@/lib/presidio-anonymizers';
 
 let ensurePromise: Promise<void> | null = null;
@@ -64,7 +65,9 @@ export async function setAnonymizerPolicy(
   orgId = 'default',
 ): Promise<AnonymizerPolicy> {
   await ensureAnonymizerPolicySchema();
-  const normalized = normalizeAnonymizerPolicy(value);
+  // NEVER persist AES key material: strip inline keys, keeping the encrypt INTENT (a keyless encrypt
+  // spec resolves the org's vaulted key at call time via bindEncryptKey).
+  const normalized = stripInlineEncryptKeys(normalizeAnonymizerPolicy(value));
   const { db } = await import('@/db');
   const { sql } = await import('drizzle-orm');
   await db.execute(sql`