PII Masking for Claude API Lives or Dies on the Ledger — Restore, Encrypt, Measure

// pii-ledger.ts — seal the restore ledger with AES-256-GCM into a shared store
// The key is injected from a KMS. Don't keep a plaintext key resident in-process for long
import { createCipheriv, createDecipheriv, randomBytes, createHash } from "node:crypto";
 
const KEY = Buffer.from(process.env.LEDGER_KEY_BASE64!, "base64"); // 32 bytes
 
export function sealLedger(ledger: Record<string, string>): string {
  const iv = randomBytes(12);
  const cipher = createCipheriv("aes-256-gcm", KEY, iv);
  const body = Buffer.concat([cipher.update(JSON.stringify(ledger), "utf8"), cipher.final()]);
  const tag = cipher.getAuthTag();
  return Buffer.concat([iv, tag, body]).toString("base64"); // iv(12)+tag(16)+body
}
 
export function openLedger(sealed: string): Record<string, string> {
  const buf = Buffer.from(sealed, "base64");
  const iv = buf.subarray(0, 12), tag = buf.subarray(12, 28), body = buf.subarray(28);
  const decipher = createDecipheriv("aes-256-gcm", KEY, iv);
  decipher.setAuthTag(tag);
  const out = Buffer.concat([decipher.update(body), decipher.final()]);
  return JSON.parse(out.toString("utf8"));
}
 
// Per-conversation key. Hash the ID so the key isn't guessable from a raw ID
export const ledgerKey = (conversationId: string) =>
  `pii:ledger:${createHash("sha256").update(conversationId).digest("hex").slice(0, 32)}`;

// pii-pipeline.ts — final Claude API wrapper. Inherit the ledger per conversation and restore the reply
import Anthropic from "@anthropic-ai/sdk";
import { detectLayer1 } from "./pii-detect";
import { detectLayer2 } from "./pii-ner";
import { sealLedger, openLedger, ledgerKey } from "./pii-ledger";
import type { Redis } from "ioredis";
 
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });
 
export async function callClaude(
  redis: Redis, conversationId: string,
  messages: { role: "user" | "assistant"; content: string }[],
): Promise<string> {
  const key = ledgerKey(conversationId);
  const sealed = await redis.get(key);
  const ledger: Record<string, string> = sealed ? openLedger(sealed) : {};
  const reverse = new Map(Object.entries(ledger).map(([t, o]) => [o, t]));
  const counters: Record<string, number> = {};
  for (const t of Object.keys(ledger)) {
    const cat = t.slice(1, t.lastIndexOf("_"));
    counters[cat] = Math.max(counters[cat] ?? 0, parseInt(t.slice(t.lastIndexOf("_") + 1), 10) || 0);
  }
  const register = (raw: string, category: string): string => {
    const ex = reverse.get(raw);
    if (ex) return ex;
    counters[category] = (counters[category] ?? 0) + 1;
    const token = `<${category}_${String(counters[category]).padStart(3, "0")}>`;
    ledger[token] = raw; reverse.set(raw, token);
    return token;
  };
 
  const masked = [];
  for (const m of messages) {
    // Run NER (Layer 2) first, then mask Layer 1 + Layer 2 by longest-string-first to avoid offset drift
    const ents = await detectLayer2(m.content);
    const items = [
      ...ents.map((e) => ({ text: e.text, category: e.category })),
      ...detectLayer1(m.content).map((s) => ({ text: s.text, category: s.category })),
    ].sort((a, b) => b.text.length - a.text.length);
    let body = m.content;
    for (const it of items) body = body.split(it.text).join(register(it.text, it.category));
    masked.push({ role: m.role, content: body });
  }
 
  // Persist the encrypted ledger (TTL = expected max conversation lifetime, e.g. 24h)
  await redis.set(key, sealLedger(ledger), "EX", 60 * 60 * 24);
 
  const res = await client.messages.create({
    model: "claude-sonnet-4-6", max_tokens: 2048,
    system: "Strings shaped like <PERSON_001> (i.e. <CATEGORY_NNN>) must be emitted verbatim — never translate or alter them.",
    messages: masked,
  });
  const raw = res.content.filter((b) => b.type === "text").map((b: any) => b.text).join("");
 
  // Restore: turn every ledger token back into its original
  let restored = raw;
  for (const [token, original] of Object.entries(ledger)) restored = restored.split(token).join(original);
  return restored;
}

# golden_eval.py — daily CI check that no PII trace remains in masked output
# Uses synthetic data only (no raw PII) and surfaces misses (false negatives) as recall
import json, re, sys
from statistics import mean
 
EMAIL = re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b")
PHONE = re.compile(r"(?:\+?81[-\s]?|0)\d{1,4}[-\s]?\d{1,4}[-\s]?\d{3,4}")
 
def leaked_count(masked: str) -> int:
    return len(EMAIL.findall(masked)) + len(PHONE.findall(masked))
 
def run(path: str, threshold: float = 0.99) -> int:
    cases = [json.loads(l) for l in open(path, encoding="utf-8")]
    recalls = []
    for c in cases:
        masked = c["masked"]            # masker output (pre-generated)
        expected = c["expected"]        # number of PII items embedded
        found = masked.count("<") - leaked_count(masked)
        recalls.append(min(found, expected) / max(expected, 1))
    r = mean(recalls) if recalls else 0.0
    leaks = sum(1 for c in cases if leaked_count(c["masked"]) > 0)
    print(f"recall={r:.4f} leaks={leaks}/{len(cases)}")
    return 0 if (r >= threshold and leaks == 0) else 1
 
if __name__ == "__main__":
    sys.exit(run(sys.argv[1]))