feat(guardrails): real image-redaction operator surface (upload→redact→review)

alichherawalla · alichherawalla · commit 43841c04493e · 2026-07-24T20:50:49.000+05:30
The adapter + governed API route + live Presidio image-redactor (g6) were
already built and are live-verified, but the UI was only a status badge — and
imageRedactionAvailable was hardcoded false, so even the badge was wrong. This
turns it into a real management surface (the CLAUDE.md bar: a signal is not a
surface):
- ImageRedactionPanel (client): upload a PNG/JPEG KYC doc → POST the governed
  /api/v1/governance/image-redaction route → review the redacted image +
  detected entities + tamper-evident receipt; honest error states.
- Real availability: the masking page resolves it from the adapter config
  (resolvePresidioImageRedactorConfig), not a hardcoded flag.
- Pure helpers (imageRedactionMediaTypeFor / imageRedactionUploadError /
  summarizeRedactionResult) isolated + 10 unit tests; same limits as the server.
- Capability map corrected honestly: image-redaction upstream+adapter+ui = yes
  (live evidence: KYC PNG redacted, sha changed 4661→3559, PHONE_NUMBER, audit
  row), workflow = partial (no app-step/pipeline auto-invokes it yet). The old
  'no adapter/route/UI' gate was fully stale.

Live-verified 2026-07-24 end-to-end through the console API against the real
engine; coverage:check green.
diff --git a/src/app/(console)/governance/guardrails/[destination]/page.tsx b/src/app/(console)/governance/guardrails/[destination]/page.tsx
@@ -11,6 +11,7 @@ import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Input } from '@/components/ui/input';
 import { getPii } from '@/lib/adapters/registry';
+import { resolvePresidioImageRedactorConfig } from '@/lib/adapters/presidio-image-redaction';
 import { guardrailsDestination, type GuardrailsDestination } from '@/lib/guardrails-destinations';
 import { listGuardrailRules } from '@/lib/guardrails-rules';
 import { readGuardrailsView, type GuardrailsView } from '@/lib/guardrails-view';
@@ -64,13 +65,20 @@ async function destinationContent(
       listGuardrailRules(orgId).catch(() => []),
       getAnonymizerPolicy(orgId).catch(() => DEFAULT_ANONYMIZER_POLICY),
     ]);
+    // Real availability: the image-redactor is usable when its URL + token are configured (the same
+    // config the adapter resolves), not a hardcoded flag.
+    const imgCfg = resolvePresidioImageRedactorConfig();
+    const imageRedactionAvailable = Boolean(imgCfg.url && imgCfg.token);
     return (
       <div className="space-y-6">
         <ManagementCard title="Masking rules">
           <GuardrailRules rules={rules} />
         </ManagementCard>
         <ManagementCard title="Anonymizer operators — how each entity is masked">
-          <PresidioAnonymizers policy={anonymizerPolicy} imageRedactionAvailable={false} />
+          <PresidioAnonymizers
+            policy={anonymizerPolicy}
+            imageRedactionAvailable={imageRedactionAvailable}
+          />
         </ManagementCard>
       </div>
     );
diff --git a/src/components/guardrails/ImageRedactionPanel.tsx b/src/components/guardrails/ImageRedactionPanel.tsx
@@ -0,0 +1,211 @@
+'use client';
+
+import { ImageSquare, ShieldCheck, Upload } from '@phosphor-icons/react/dist/ssr';
+import { useId, useRef, useState } from 'react';
+import { toast } from 'sonner';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import {
+  type ImageRedactionEvidence,
+  imageRedactionMediaTypeFor,
+  imageRedactionUploadError,
+  summarizeRedactionResult,
+} from '@/lib/image-redaction';
+
+// The OPERATOR-facing image redaction surface: upload a KYC document image (an OVD scan), redact the
+// PII regions through the governed /api/v1/governance/image-redaction route (which drives the live
+// Presidio image-redactor + Tesseract OCR, records an audited receipt), and REVIEW the redacted image
+// + the detected entities + the tamper-evident receipt. This is the real management surface — not a
+// status badge. Pure validation/summary (imageRedactionUploadError / summarizeRedactionResult) is
+// isolated + unit-tested in lib/image-redaction; this component is the thin upload/render glue.
+
+interface RedactionResponse {
+  redactedImageBase64: string;
+  mediaType: string;
+  evidence: ImageRedactionEvidence;
+}
+
+// Read a File to canonical base64 (strip the data: prefix) in the browser.
+function fileToBase64(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onerror = () => reject(new Error('Could not read the file.'));
+    reader.onload = () => {
+      const result = String(reader.result ?? '');
+      const comma = result.indexOf(',');
+      resolve(comma >= 0 ? result.slice(comma + 1) : result);
+    };
+    reader.readAsDataURL(file);
+  });
+}
+
+export function ImageRedactionPanel({ available }: Readonly<{ available: boolean }>) {
+  const inputId = useId();
+  const purposeId = useId();
+  const fileRef = useRef<HTMLInputElement>(null);
+  const [purpose, setPurpose] = useState('KYC document redaction');
+  const [busy, setBusy] = useState(false);
+  const [result, setResult] = useState<RedactionResponse | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  if (!available) {
+    return (
+      <div className="space-y-1 rounded-md border border-dashed border-border p-4">
+        <div className="flex items-center gap-2">
+          <ImageSquare className="size-4 text-muted-foreground" />
+          <span className="text-sm font-medium">Document image redaction</span>
+          <Badge variant="secondary">engine not deployed</Badge>
+        </div>
+        <p className="text-xs text-muted-foreground">
+          Redacting PII from KYC document images (OVDs) needs the Presidio image-redactor service,
+          which is not part of this deployment. Text masking above is fully live.
+        </p>
+      </div>
+    );
+  }
+
+  async function onRedact(): Promise<void> {
+    setError(null);
+    const file = fileRef.current?.files?.[0];
+    if (!file) {
+      setError('Choose a PNG or JPEG image first.');
+      return;
+    }
+    const fileError = imageRedactionUploadError({ type: file.type, size: file.size });
+    if (fileError) {
+      setError(fileError);
+      return;
+    }
+    if (purpose.trim().length < 3) {
+      setError('Enter a purpose (why this document is being redacted) — 3 characters or more.');
+      return;
+    }
+    setBusy(true);
+    setResult(null);
+    try {
+      const imageBase64 = await fileToBase64(file);
+      const res = await fetch('/api/v1/governance/image-redaction', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          imageBase64,
+          mediaType: imageRedactionMediaTypeFor(file.type),
+          purpose: purpose.trim(),
+        }),
+      });
+      const body = (await res.json().catch(() => ({}))) as Partial<RedactionResponse> & {
+        error?: string;
+      };
+      if (!res.ok) {
+        setError(body.error ?? `Redaction failed (HTTP ${res.status}).`);
+        return;
+      }
+      setResult(body as RedactionResponse);
+      toast.success('Image redacted');
+    } catch {
+      setError('Could not reach the redaction service.');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div className="space-y-4 rounded-md border border-border p-4">
+      <div className="flex items-center gap-2">
+        <ImageSquare className="size-4 text-primary" />
+        <span className="text-sm font-medium">Document image redaction</span>
+        <Badge>available</Badge>
+      </div>
+      <p className="text-xs text-muted-foreground">
+        Upload a KYC document image (an OVD scan). PII regions are detected by OCR and blacked out
+        before the file moves; the original never leaves this request. Every redaction records a
+        tamper-evident receipt in the audit log.
+      </p>
+
+      <div className="grid gap-4 lg:grid-cols-[minmax(0,20rem)_1fr]">
+        <div className="space-y-3">
+          <div className="space-y-1.5">
+            <Label htmlFor={inputId} className="text-xs">
+              Document image (PNG or JPEG, up to 8 MiB)
+            </Label>
+            <Input
+              id={inputId}
+              ref={fileRef}
+              type="file"
+              accept="image/png,image/jpeg"
+              className="text-xs"
+              onChange={() => {
+                setError(null);
+                setResult(null);
+              }}
+            />
+          </div>
+          <div className="space-y-1.5">
+            <Label htmlFor={purposeId} className="text-xs">
+              Purpose
+            </Label>
+            <Input
+              id={purposeId}
+              value={purpose}
+              onChange={(e) => setPurpose(e.target.value)}
+              placeholder="Why is this document being redacted?"
+              className="text-xs"
+            />
+          </div>
+          <Button type="button" size="sm" onClick={onRedact} disabled={busy}>
+            <Upload className="size-4" />
+            {busy ? 'Redacting…' : 'Redact PII'}
+          </Button>
+          {error ? (
+            <p role="alert" className="text-xs text-destructive">
+              {error}
+            </p>
+          ) : null}
+        </div>
+
+        {result ? (
+          <div className="space-y-3">
+            <div className="flex items-center gap-2">
+              <ShieldCheck className="size-4 text-primary" weight="fill" />
+              <span className="text-sm font-medium">{summarizeRedactionResult(result.evidence)}</span>
+            </div>
+            {/* eslint-disable-next-line @next/next/no-img-element */}
+            <img
+              src={`data:${result.mediaType};base64,${result.redactedImageBase64}`}
+              alt="Redacted document — PII regions blacked out"
+              className="max-h-72 w-auto rounded border border-border"
+            />
+            <dl className="grid grid-cols-2 gap-x-4 gap-y-1 text-xs text-muted-foreground">
+              <dt>Engine</dt>
+              <dd className="text-foreground">
+                {result.evidence.engine} {result.evidence.engineVersion}
+              </dd>
+              <dt>OCR</dt>
+              <dd className="text-foreground">{result.evidence.ocrEngine}</dd>
+              <dt>Detected</dt>
+              <dd className="text-foreground">
+                {result.evidence.entities.length
+                  ? result.evidence.entities
+                      .map((e) => `${e.entityType} ×${e.count}`)
+                      .join(', ')
+                  : 'none'}
+              </dd>
+              <dt>Duration</dt>
+              <dd className="text-foreground">{result.evidence.durationMs} ms</dd>
+              <dt>Receipt</dt>
+              <dd className="break-all font-mono text-[11px] text-foreground">
+                {result.evidence.policy.receiptId}
+              </dd>
+            </dl>
+          </div>
+        ) : (
+          <div className="flex items-center justify-center rounded border border-dashed border-border p-6 text-xs text-muted-foreground">
+            The redacted image and its evidence receipt appear here.
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/guardrails/PresidioAnonymizers.tsx b/src/components/guardrails/PresidioAnonymizers.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { ImageSquare, Plus, Trash } from '@phosphor-icons/react/dist/ssr';
+import { Plus, Trash } from '@phosphor-icons/react/dist/ssr';
 import { useRouter } from 'next/navigation';
 import { useId, useState } from 'react';
 import { toast } from 'sonner';
@@ -18,6 +18,7 @@ import {
   TableRow,
 } from '@/components/ui/table';
 import { Textarea } from '@/components/ui/textarea';
+import { ImageRedactionPanel } from '@/components/guardrails/ImageRedactionPanel';
 import {
   ANONYMIZE_OPERATORS,
   type AnonymizeOperator,
@@ -252,21 +253,8 @@ export function PresidioAnonymizers({
           ) : null}
         </div>
 
-        {/* Image redaction — honest capability signal */}
-        <div className="space-y-1 rounded-md border border-dashed border-border p-4">
-          <div className="flex items-center gap-2">
-            <ImageSquare className="size-4 text-muted-foreground" />
-            <span className="text-sm font-medium">Document image redaction</span>
-            <Badge variant={imageRedactionAvailable ? 'default' : 'secondary'}>
-              {imageRedactionAvailable ? 'available' : 'engine not deployed'}
-            </Badge>
-          </div>
-          <p className="text-xs text-muted-foreground">
-            {imageRedactionAvailable
-              ? 'Upload a KYC document image to redact PII regions before it moves.'
-              : 'Redacting PII from KYC document IMAGES (OVDs) needs the Presidio image-redactor service, which is not part of this deployment. Text masking above is fully live.'}
-          </p>
-        </div>
+        {/* Image redaction — the real upload → redact → review surface */}
+        <ImageRedactionPanel available={imageRedactionAvailable} />
       </div>
     </div>
   );
diff --git a/src/lib/image-redaction.ts b/src/lib/image-redaction.ts
@@ -285,3 +285,45 @@ export function summarizeImageRedactionEntities(
     .sort(([left], [right]) => left.localeCompare(right))
     .map(([entityType, evidence]) => ({ entityType, ...evidence }));
 }
+
+// ─── Operator-UI PURE helpers (client-side, zero-IO) ────────────────────────────────────────────
+// The upload panel validates a chosen file BEFORE encoding + posting it, so an over-limit or
+// wrong-type file is rejected instantly with an honest message instead of a wasted round-trip. Same
+// limits the server enforces (IMAGE_REDACTION_LIMITS) — one source of truth, no drift.
+
+/** Map a browser File.type to the supported media type, or null if unsupported. PURE. */
+export function imageRedactionMediaTypeFor(fileType: string): ImageRedactionMediaType | null {
+  if (fileType === 'image/png') return 'image/png';
+  if (fileType === 'image/jpeg' || fileType === 'image/jpg') return 'image/jpeg';
+  return null;
+}
+
+/**
+ * Validate a chosen upload against the server's real limits. Returns an honest error string, or null
+ * when the file is acceptable. PURE — takes the minimal {type,size} shape so it is unit-testable
+ * without a DOM File.
+ */
+export function imageRedactionUploadError(file: { type: string; size: number }): string | null {
+  if (!imageRedactionMediaTypeFor(file.type)) return 'Only PNG and JPEG images are supported.';
+  if (file.size <= 0) return 'The file is empty.';
+  if (file.size > IMAGE_REDACTION_LIMITS.maxBytes) {
+    const mib = Math.round(IMAGE_REDACTION_LIMITS.maxBytes / (1024 * 1024));
+    return `Image exceeds the ${mib} MiB limit.`;
+  }
+  return null;
+}
+
+/**
+ * A short human summary of what a redaction did, for the review panel. PURE.
+ *   • no entities → an honest "screened, nothing detected" (the image is still returned re-encoded).
+ *   • entities    → "PAN ×1, PHONE_NUMBER ×2" style, most-frequent first.
+ */
+export function summarizeRedactionResult(evidence: ImageRedactionEvidence): string {
+  const list = evidence.entities;
+  if (!list.length) return 'Screened — no PII detected in the image.';
+  const parts = [...list]
+    .sort((a, b) => b.count - a.count || a.entityType.localeCompare(b.entityType))
+    .map((e) => `${e.entityType} ×${e.count}`);
+  const total = list.reduce((sum, e) => sum + e.count, 0);
+  return `Redacted ${total} PII region${total === 1 ? '' : 's'}: ${parts.join(', ')}.`;
+}
diff --git a/src/lib/service-capabilities/runtime-governance-operations.ts b/src/lib/service-capabilities/runtime-governance-operations.ts
@@ -1670,18 +1670,18 @@ export const RUNTIME_GOVERNANCE_OPERATIONS_AUDITS = [
         'image-redaction',
         'Image PII redaction',
         'Detect and redact PII in images and scanned documents.',
-        PRESIDIO_ROUTE,
-        'Inspect Presidio status',
-        'The deployed analyzer/anonymizer pair has no image-redactor adapter, API route, or review UI.',
+        '/governance/guardrails/masking',
+        'Redact a document image',
+        'Operator upload→redact→review is live and audited; no automatic app-step or pipeline invokes image redaction yet (a manual governed surface, not an in-line workflow step).',
         [
           'yes',
-          'Presidio provides an image redactor capability.',
-          'no',
-          'No image-redactor service or adapter is registered.',
-          'no',
-          'No image redaction UI exists.',
-          'no',
-          'No document or media workflow invokes Presidio image redaction.',
+          'Presidio image-redactor 0.0.59 deployed on g6 (offgrid-console-presidio-image-redactor-1, :5003), reached via the S1 :8940 tunnel.',
+          'yes',
+          'createPresidioImageRedactor (src/lib/adapters/presidio-image-redaction.ts) posts to /v1/redact, contract-checks the engine/OCR/media response, and verifies the output bytes differ from the input. Live-verified 2026-07-24: a KYC PNG through /api/v1/governance/image-redaction returned HTTP 200, image sha CHANGED (4661→3559 bytes), PHONE_NUMBER redacted, receipt imgred_… + governance.image.redact audit row (outcome redacted).',
+          'yes',
+          'ImageRedactionPanel (Governance → Guardrails → Masking): upload a PNG/JPEG, redact via the governed route, review the redacted image + detected entities + tamper-evident receipt. Availability resolves from the real adapter config, not a hardcoded flag.',
+          'partial',
+          'The governed API route + operator UI are live and audited, but no App step or pipeline stage invokes image redaction automatically on document ingress.',
         ],
       ),
     ],
diff --git a/test/image-redaction.test.ts b/test/image-redaction.test.ts
