@studio-foundation/anonymizer 0.3.0-beta.1

package/README.md

@@ -0,0 +1,90 @@
+# @studio-foundation/anonymizer
+
+PII detection and anonymization library. Replaces sensitive data with consistent tokens before sending to LLMs, with a keymap to restore the original values afterward.
+
+## Role
+
+anonymizer sits at the bottom of the stack — a pure utility with zero `@studio/*` dependencies. The runner wraps it in `AnonymizationMiddleware` and injects it transparently into the agent execution loop.
+
+```
+user data → anonymize() → [PERSON_1], [EMAIL_1] → LLM → deanonymize() → original values
+```
+
+## Key exports
+
+```typescript
+import { anonymize, deanonymize, Tokenizer } from '@studio-foundation/anonymizer';
+import type { PIICategory, PIIDetectionResult, AnonymizerOptions } from '@studio-foundation/anonymizer';
+
+// Anonymize a string
+const { text, keymap } = anonymize('Hi Marie, call me at 555-867-5309');
+// text   → "Hi [PERSON_1], call me at [PHONE_1]"
+// keymap → { "PERSON_1": "Marie", "PHONE_1": "555-867-5309" }
+
+// Restore originals
+const original = deanonymize(text, keymap);
+// → "Hi Marie, call me at 555-867-5309"
+
+// Cross-stage consistency — pass the keymap from a previous call
+const { text: text2, keymap: keymap2 } = anonymize(nextChunk, { seedKeymap: keymap });
+// PERSON_1 still maps to "Marie" across calls
+```
+
+## PII categories
+
+| Category | Token format | What it detects |
+|----------|-------------|-----------------|
+| `person` | `PERSON_N` | Names after salutations (Dear, Hi, Mr., Dr., etc.) — best effort |
+| `email` | `EMAIL_N` | Email addresses |
+| `phone` | `PHONE_N` | US phone numbers (10 digits, various formats) |
+| `ssn` | `SSN_N` | Social security numbers (ddd-dd-dddd) |
+| `credit_card` | `CREDIT_CARD_N` | 16-digit card numbers |
+| `address` | `ADDRESS_N` | Reserved (detection not yet implemented) |
+
+## Detection strategy
+
+Two-phase detection on each call:
+
+1. **Regex (high precision)** — email, phone, SSN, credit card. Structural patterns anchored to avoid false positives (e.g. SSN regex uses strict hyphen format to avoid matching phone fragments).
+
+2. **Person names (best effort)** — salutation-gated pattern (`Dear X`, `Hi X`, `Mr. X`, etc.). Only catches explicitly addressed names — not bare occurrences.
+
+Spans are non-overlapping. If two patterns match the same range, the first one wins and the position is marked occupied.
+
+## Token consistency
+
+Same value → same token, within and across calls:
+
+```typescript
+// Within one call: two mentions of the same email → same token
+anonymize('Contact foo@bar.com or reach foo@bar.com')
+// → "Contact [EMAIL_1] or reach [EMAIL_1]"
+
+// Across calls: seed the next call with the previous keymap
+const { text: t1, keymap: km1 } = anonymize(stage1Output);
+const { text: t2, keymap: km2 } = anonymize(stage2Output, { seedKeymap: km1 });
+// EMAIL_1 is the same person in t1 and t2
+```
+
+## Filter by category
+
+```typescript
+// Only anonymize emails — leave names and phones unchanged
+const { text } = anonymize(rawText, { categories: ['email'] });
+```
+
+## How it's used in Studio
+
+The runner wraps this in `AnonymizationMiddleware` (in `runner/src/middleware/anonymization.ts`). When `anonymize: true` is set on an agent or a run:
+
+1. Task description is anonymized before being sent to the LLM
+2. Tool results are anonymized before being injected back into context
+3. The accumulated keymap is written to `.studio/runs/anonymization/<run-id>.keymap.json` for post-run inspection
+
+The middleware is wired by the engine and passed to `runAgent()` — user code doesn't call `anonymize()` directly.
+
+## Rules
+
+- **Zero `@studio/*` dependencies.** This package must stay a pure utility.
+- `anonymize()` is stateless — the `Tokenizer` is created fresh each call (or seeded via `seedKeymap`).
+- Person detection is always best-effort and non-fatal — failures are silently skipped.

package/dist/detector.d.ts

@@ -0,0 +1,7 @@
+import type { PIISpan } from './types.js';
+/**
+ * Detect PII spans in text.
+ * Returns non-overlapping spans sorted by position.
+ */
+export declare function detectPII(text: string): PIISpan[];
+//# sourceMappingURL=detector.d.ts.map

package/dist/detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../src/detector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,OAAO,EAAE,MAAM,YAAY,CAAC;AA0BvD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAyBjD"}

package/dist/detector.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectPII = detectPII;
+// Regex patterns for structural PII (high precision)
+const PATTERNS = [
+    {
+        category: 'email',
+        regex: /\b[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}\b/g,
+    },
+    {
+        category: 'phone',
+        // US phone: must be at least 10 digits. Require optional country code + area code.
+        // Anchored to avoid matching partial SSN-like strings.
+        regex: /\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]\d{3}[-.\s]\d{4}\b/g,
+    },
+    {
+        category: 'ssn',
+        // SSN: exactly ddd-dd-dddd with hyphens (strict format, not dots or spaces
+        // to avoid collision with phone numbers already consumed)
+        regex: /\b\d{3}-\d{2}-\d{4}\b/g,
+    },
+    {
+        category: 'credit_card',
+        regex: /\b(?:\d{4}[-\s]?){3}\d{4}\b/g,
+    },
+];
+/**
+ * Detect PII spans in text.
+ * Returns non-overlapping spans sorted by position.
+ */
+function detectPII(text) {
+    const spans = [];
+    const occupied = new Set();
+    // Phase 1: Structural PII via regex
+    for (const { category, regex } of PATTERNS) {
+        regex.lastIndex = 0;
+        let match;
+        while ((match = regex.exec(text)) !== null) {
+            const start = match.index;
+            const end = start + match[0].length;
+            if (isOccupied(occupied, start, end))
+                continue;
+            markOccupied(occupied, start, end);
+            spans.push({ start, end, category, value: match[0] });
+        }
+    }
+    // Phase 2: Person names — best-effort via @redactpii/node
+    try {
+        detectPersons(text, occupied, spans);
+    }
+    catch {
+        // Person detection is best-effort; silently skip on any error
+    }
+    return spans.sort((a, b) => a.start - b.start);
+}
+function isOccupied(occupied, start, end) {
+    for (let i = start; i < end; i++) {
+        if (occupied.has(i))
+            return true;
+    }
+    return false;
+}
+function markOccupied(occupied, start, end) {
+    for (let i = start; i < end; i++) {
+        occupied.add(i);
+    }
+}
+function detectPersons(text, occupied, spans) {
+    // The @redactpii/node NAME pattern only catches names after salutations
+    // (Dear, Hi, Hello, Hey, etc.) — not bare names. We replicate that pattern
+    // here and use it directly, avoiding the ESM/CJS import complexity.
+    // This gives best-effort detection for explicitly addressed names.
+    const salutationPattern = /(?:dear|hi|hello|greetings|hey(?:\s+there)?|mr\.?|mrs\.?|ms\.?|dr\.?|prof\.?)\s+([A-Z][a-zA-ZÀ-ÿ'\-]+(?:\s+[A-Z][a-zA-ZÀ-ÿ'\-]+)*)/gi;
+    let match;
+    salutationPattern.lastIndex = 0;
+    while ((match = salutationPattern.exec(text)) !== null) {
+        // match[1] is the captured name group
+        const nameValue = match[1];
+        if (!nameValue)
+            continue;
+        // Find the actual start position of the captured name within the full match
+        const fullMatchStart = match.index;
+        const nameOffset = match[0].indexOf(nameValue);
+        const start = fullMatchStart + nameOffset;
+        const end = start + nameValue.length;
+        if (isOccupied(occupied, start, end))
+            continue;
+        markOccupied(occupied, start, end);
+        spans.push({ start, end, category: 'person', value: nameValue });
+    }
+}
+//# sourceMappingURL=detector.js.map

package/dist/detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.js","sourceRoot":"","sources":["../src/detector.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import type { PIIDetectionResult, AnonymizerOptions } from './types.js';
+export type { PIICategory, PIIDetectionResult, AnonymizerOptions } from './types.js';
+export { Tokenizer } from './tokenizer.js';
+/**
+ * Anonymize PII in text. Returns anonymized text + keymap (token → original).
+ * Same PII value always gets the same token within a call.
+ * Pass seedKeymap to maintain consistency across multiple calls.
+ */
+export declare function anonymize(text: string, options?: AnonymizerOptions): PIIDetectionResult;
+/**
+ * Restore original PII values from keymap.
+ * Tokens not in the keymap are left unchanged.
+ */
+export declare function deanonymize(text: string, keymap: Record<string, string>): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAExE,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACrF,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,kBAAkB,CAyBvF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAQhF"}

package/dist/index.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tokenizer = void 0;
+exports.anonymize = anonymize;
+exports.deanonymize = deanonymize;
+const detector_js_1 = require("./detector.js");
+const tokenizer_js_1 = require("./tokenizer.js");
+var tokenizer_js_2 = require("./tokenizer.js");
+Object.defineProperty(exports, "Tokenizer", { enumerable: true, get: function () { return tokenizer_js_2.Tokenizer; } });
+/**
+ * Anonymize PII in text. Returns anonymized text + keymap (token → original).
+ * Same PII value always gets the same token within a call.
+ * Pass seedKeymap to maintain consistency across multiple calls.
+ */
+function anonymize(text, options) {
+    const spans = (0, detector_js_1.detectPII)(text);
+    const filtered = options?.categories
+        ? spans.filter(s => options.categories.includes(s.category))
+        : spans;
+    const tokenizer = new tokenizer_js_1.Tokenizer();
+    // Seed from existing keymap for cross-call consistency
+    if (options?.seedKeymap && Object.keys(options.seedKeymap).length > 0) {
+        tokenizer.loadKeymap(options.seedKeymap);
+    }
+    if (filtered.length === 0) {
+        return { text, keymap: tokenizer.getKeymap() };
+    }
+    // Replace spans from right to left to preserve character positions
+    const sortedDesc = [...filtered].sort((a, b) => b.start - a.start);
+    let result = text;
+    for (const span of sortedDesc) {
+        const token = tokenizer.tokenize(span.value, span.category);
+        result = result.slice(0, span.start) + token + result.slice(span.end);
+    }
+    return { text: result, keymap: tokenizer.getKeymap() };
+}
+/**
+ * Restore original PII values from keymap.
+ * Tokens not in the keymap are left unchanged.
+ */
+function deanonymize(text, keymap) {
+    let result = text;
+    // Sort by token length descending so EMAIL_10 is replaced before EMAIL_1
+    const sorted = Object.entries(keymap).sort((a, b) => b[0].length - a[0].length);
+    for (const [token, original] of sorted) {
+        result = result.replaceAll(token, original);
+    }
+    return result;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAYA,8BAyBC;AAMD,kCAQC;AAnDD,+CAA0C;AAC1C,iDAA2C;AAI3C,+CAA2C;AAAlC,yGAAA,SAAS,OAAA;AAElB;;;;GAIG;AACH,SAAgB,SAAS,CAAC,IAAY,EAAE,OAA2B;IACjE,MAAM,KAAK,GAAG,IAAA,uBAAS,EAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,QAAQ,GAAG,OAAO,EAAE,UAAU;QAClC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,UAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QAC7D,CAAC,CAAC,KAAK,CAAC;IAEV,MAAM,SAAS,GAAG,IAAI,wBAAS,EAAE,CAAC;IAClC,uDAAuD;IACvD,IAAI,OAAO,EAAE,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtE,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,SAAS,EAAE,EAAE,CAAC;IACjD,CAAC;IAED,mEAAmE;IACnE,MAAM,UAAU,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IACnE,IAAI,MAAM,GAAG,IAAI,CAAC;IAClB,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC5D,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxE,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,SAAS,EAAE,EAAE,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,SAAgB,WAAW,CAAC,IAAY,EAAE,MAA8B;IACtE,IAAI,MAAM,GAAG,IAAI,CAAC;IAClB,yEAAyE;IACzE,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAChF,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,MAAM,EAAE,CAAC;QACvC,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/tokenizer.d.ts

@@ -0,0 +1,17 @@
+import type { PIICategory } from './types.js';
+export declare class Tokenizer {
+    private inverse;
+    private keymap;
+    private counters;
+    /**
+     * Get or create a consistent sequential token for a PII value.
+     */
+    tokenize(value: string, category: PIICategory): string;
+    getKeymap(): Record<string, string>;
+    /**
+     * Load an existing keymap (for cross-stage continuity).
+     * Populates inverse map so existing tokens are reused.
+     */
+    loadKeymap(keymap: Record<string, string>): void;
+}
+//# sourceMappingURL=tokenizer.d.ts.map

package/dist/tokenizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenizer.d.ts","sourceRoot":"","sources":["../src/tokenizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAW9C,qBAAa,SAAS;IAEpB,OAAO,CAAC,OAAO,CAA6B;IAE5C,OAAO,CAAC,MAAM,CAA6B;IAE3C,OAAO,CAAC,QAAQ,CAAkC;IAElD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,MAAM;IAetD,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAInC;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;CAiBjD"}

package/dist/tokenizer.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tokenizer = void 0;
+const CATEGORY_PREFIX = {
+    person: 'PERSON',
+    email: 'EMAIL',
+    phone: 'PHONE',
+    address: 'ADDRESS',
+    ssn: 'SSN',
+    credit_card: 'CREDIT_CARD',
+};
+class Tokenizer {
+    // original value → token
+    inverse = new Map();
+    // token → original value
+    keymap = new Map();
+    // category → counter
+    counters = new Map();
+    /**
+     * Get or create a consistent sequential token for a PII value.
+     */
+    tokenize(value, category) {
+        const existing = this.inverse.get(value);
+        if (existing)
+            return existing;
+        const counter = (this.counters.get(category) ?? 0) + 1;
+        this.counters.set(category, counter);
+        const prefix = CATEGORY_PREFIX[category];
+        const token = `${prefix}_${counter}`;
+        this.inverse.set(value, token);
+        this.keymap.set(token, value);
+        return token;
+    }
+    getKeymap() {
+        return Object.fromEntries(this.keymap);
+    }
+    /**
+     * Load an existing keymap (for cross-stage continuity).
+     * Populates inverse map so existing tokens are reused.
+     */
+    loadKeymap(keymap) {
+        for (const [token, value] of Object.entries(keymap)) {
+            this.keymap.set(token, value);
+            this.inverse.set(value, token);
+            // Restore counter state from token name (e.g. PERSON_3 → counter = 3)
+            const match = token.match(/^([A-Z_]+)_(\d+)$/);
+            if (match) {
+                const cat = Object.entries(CATEGORY_PREFIX).find(([, p]) => p === match[1])?.[0];
+                if (cat) {
+                    const n = parseInt(match[2], 10);
+                    if ((this.counters.get(cat) ?? 0) < n) {
+                        this.counters.set(cat, n);
+                    }
+                }
+            }
+        }
+    }
+}
+exports.Tokenizer = Tokenizer;
+//# sourceMappingURL=tokenizer.js.map

package/dist/tokenizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenizer.js","sourceRoot":"","sources":["../src/tokenizer.ts"],"names":[],"mappings":";;;AAEA,MAAM,eAAe,GAAgC;IACnD,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,GAAG,EAAE,KAAK;IACV,WAAW,EAAE,aAAa;CAC3B,CAAC;AAEF,MAAa,SAAS;IACpB,yBAAyB;IACjB,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,yBAAyB;IACjB,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,qBAAqB;IACb,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;IAElD;;OAEG;IACH,QAAQ,CAAC,KAAa,EAAE,QAAqB;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAE9B,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACvD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAErC,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;QACzC,MAAM,KAAK,GAAG,GAAG,MAAM,IAAI,OAAO,EAAE,CAAC;QAErC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,SAAS;QACP,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,MAA8B;QACvC,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACpD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAC9B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAC/B,sEAAsE;YACtE,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;YAC/C,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAA4B,CAAC;gBAC5G,IAAI,GAAG,EAAE,CAAC;oBACR,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACjC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;wBACtC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;oBAC5B,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAnDD,8BAmDC"}

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+export type PIICategory = 'person' | 'email' | 'phone' | 'address' | 'ssn' | 'credit_card';
+export interface PIISpan {
+    start: number;
+    end: number;
+    category: PIICategory;
+    value: string;
+}
+export interface PIIDetectionResult {
+    text: string;
+    keymap: Record<string, string>;
+}
+export interface AnonymizerOptions {
+    categories?: PIICategory[];
+    seedKeymap?: Record<string, string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,OAAO,GACP,OAAO,GACP,SAAS,GACT,KAAK,GACL,aAAa,CAAC;AAElB,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,WAAW,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,WAAW,EAAE,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@studio-foundation/anonymizer",
+  "version": "0.3.0-beta.1",
+  "description": "PII detection and anonymization with consistent token mapping",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "pii",
+    "anonymization",
+    "privacy"
+  ],
+  "author": "Ariane Guay",
+  "license": "AGPL-3.0-only",
+  "dependencies": {
+    "@redactpii/node": "^1.0.16"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@types/node": "^25.2.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}

package/src/detector.ts

@@ -0,0 +1,97 @@
+import type { PIICategory, PIISpan } from './types.js';
+
+// Regex patterns for structural PII (high precision)
+const PATTERNS: Array<{ category: PIICategory; regex: RegExp }> = [
+  {
+    category: 'email',
+    regex: /\b[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}\b/g,
+  },
+  {
+    category: 'phone',
+    // US phone: must be at least 10 digits. Require optional country code + area code.
+    // Anchored to avoid matching partial SSN-like strings.
+    regex: /\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]\d{3}[-.\s]\d{4}\b/g,
+  },
+  {
+    category: 'ssn',
+    // SSN: exactly ddd-dd-dddd with hyphens (strict format, not dots or spaces
+    // to avoid collision with phone numbers already consumed)
+    regex: /\b\d{3}-\d{2}-\d{4}\b/g,
+  },
+  {
+    category: 'credit_card',
+    regex: /\b(?:\d{4}[-\s]?){3}\d{4}\b/g,
+  },
+];
+
+/**
+ * Detect PII spans in text.
+ * Returns non-overlapping spans sorted by position.
+ */
+export function detectPII(text: string): PIISpan[] {
+  const spans: PIISpan[] = [];
+  const occupied = new Set<number>();
+
+  // Phase 1: Structural PII via regex
+  for (const { category, regex } of PATTERNS) {
+    regex.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = regex.exec(text)) !== null) {
+      const start = match.index;
+      const end = start + match[0].length;
+      if (isOccupied(occupied, start, end)) continue;
+      markOccupied(occupied, start, end);
+      spans.push({ start, end, category, value: match[0] });
+    }
+  }
+
+  // Phase 2: Person names — best-effort via @redactpii/node
+  try {
+    detectPersons(text, occupied, spans);
+  } catch {
+    // Person detection is best-effort; silently skip on any error
+  }
+
+  return spans.sort((a, b) => a.start - b.start);
+}
+
+function isOccupied(occupied: Set<number>, start: number, end: number): boolean {
+  for (let i = start; i < end; i++) {
+    if (occupied.has(i)) return true;
+  }
+  return false;
+}
+
+function markOccupied(occupied: Set<number>, start: number, end: number): void {
+  for (let i = start; i < end; i++) {
+    occupied.add(i);
+  }
+}
+
+function detectPersons(text: string, occupied: Set<number>, spans: PIISpan[]): void {
+  // The @redactpii/node NAME pattern only catches names after salutations
+  // (Dear, Hi, Hello, Hey, etc.) — not bare names. We replicate that pattern
+  // here and use it directly, avoiding the ESM/CJS import complexity.
+  // This gives best-effort detection for explicitly addressed names.
+  const salutationPattern =
+    /(?:dear|hi|hello|greetings|hey(?:\s+there)?|mr\.?|mrs\.?|ms\.?|dr\.?|prof\.?)\s+([A-Z][a-zA-ZÀ-ÿ'\-]+(?:\s+[A-Z][a-zA-ZÀ-ÿ'\-]+)*)/gi;
+
+  let match: RegExpExecArray | null;
+  salutationPattern.lastIndex = 0;
+
+  while ((match = salutationPattern.exec(text)) !== null) {
+    // match[1] is the captured name group
+    const nameValue = match[1];
+    if (!nameValue) continue;
+
+    // Find the actual start position of the captured name within the full match
+    const fullMatchStart = match.index;
+    const nameOffset = match[0].indexOf(nameValue);
+    const start = fullMatchStart + nameOffset;
+    const end = start + nameValue.length;
+
+    if (isOccupied(occupied, start, end)) continue;
+    markOccupied(occupied, start, end);
+    spans.push({ start, end, category: 'person', value: nameValue });
+  }
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+import { detectPII } from './detector.js';
+import { Tokenizer } from './tokenizer.js';
+import type { PIIDetectionResult, AnonymizerOptions } from './types.js';
+
+export type { PIICategory, PIIDetectionResult, AnonymizerOptions } from './types.js';
+export { Tokenizer } from './tokenizer.js';
+
+/**
+ * Anonymize PII in text. Returns anonymized text + keymap (token → original).
+ * Same PII value always gets the same token within a call.
+ * Pass seedKeymap to maintain consistency across multiple calls.
+ */
+export function anonymize(text: string, options?: AnonymizerOptions): PIIDetectionResult {
+  const spans = detectPII(text);
+  const filtered = options?.categories
+    ? spans.filter(s => options.categories!.includes(s.category))
+    : spans;
+
+  const tokenizer = new Tokenizer();
+  // Seed from existing keymap for cross-call consistency
+  if (options?.seedKeymap && Object.keys(options.seedKeymap).length > 0) {
+    tokenizer.loadKeymap(options.seedKeymap);
+  }
+
+  if (filtered.length === 0) {
+    return { text, keymap: tokenizer.getKeymap() };
+  }
+
+  // Replace spans from right to left to preserve character positions
+  const sortedDesc = [...filtered].sort((a, b) => b.start - a.start);
+  let result = text;
+  for (const span of sortedDesc) {
+    const token = tokenizer.tokenize(span.value, span.category);
+    result = result.slice(0, span.start) + token + result.slice(span.end);
+  }
+
+  return { text: result, keymap: tokenizer.getKeymap() };
+}
+
+/**
+ * Restore original PII values from keymap.
+ * Tokens not in the keymap are left unchanged.
+ */
+export function deanonymize(text: string, keymap: Record<string, string>): string {
+  let result = text;
+  // Sort by token length descending so EMAIL_10 is replaced before EMAIL_1
+  const sorted = Object.entries(keymap).sort((a, b) => b[0].length - a[0].length);
+  for (const [token, original] of sorted) {
+    result = result.replaceAll(token, original);
+  }
+  return result;
+}

package/src/tokenizer.ts

@@ -0,0 +1,63 @@
+import type { PIICategory } from './types.js';
+
+const CATEGORY_PREFIX: Record<PIICategory, string> = {
+  person: 'PERSON',
+  email: 'EMAIL',
+  phone: 'PHONE',
+  address: 'ADDRESS',
+  ssn: 'SSN',
+  credit_card: 'CREDIT_CARD',
+};
+
+export class Tokenizer {
+  // original value → token
+  private inverse = new Map<string, string>();
+  // token → original value
+  private keymap = new Map<string, string>();
+  // category → counter
+  private counters = new Map<PIICategory, number>();
+
+  /**
+   * Get or create a consistent sequential token for a PII value.
+   */
+  tokenize(value: string, category: PIICategory): string {
+    const existing = this.inverse.get(value);
+    if (existing) return existing;
+
+    const counter = (this.counters.get(category) ?? 0) + 1;
+    this.counters.set(category, counter);
+
+    const prefix = CATEGORY_PREFIX[category];
+    const token = `${prefix}_${counter}`;
+
+    this.inverse.set(value, token);
+    this.keymap.set(token, value);
+    return token;
+  }
+
+  getKeymap(): Record<string, string> {
+    return Object.fromEntries(this.keymap);
+  }
+
+  /**
+   * Load an existing keymap (for cross-stage continuity).
+   * Populates inverse map so existing tokens are reused.
+   */
+  loadKeymap(keymap: Record<string, string>): void {
+    for (const [token, value] of Object.entries(keymap)) {
+      this.keymap.set(token, value);
+      this.inverse.set(value, token);
+      // Restore counter state from token name (e.g. PERSON_3 → counter = 3)
+      const match = token.match(/^([A-Z_]+)_(\d+)$/);
+      if (match) {
+        const cat = Object.entries(CATEGORY_PREFIX).find(([, p]) => p === match[1])?.[0] as PIICategory | undefined;
+        if (cat) {
+          const n = parseInt(match[2], 10);
+          if ((this.counters.get(cat) ?? 0) < n) {
+            this.counters.set(cat, n);
+          }
+        }
+      }
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,24 @@
+export type PIICategory =
+  | 'person'
+  | 'email'
+  | 'phone'
+  | 'address'
+  | 'ssn'
+  | 'credit_card';
+
+export interface PIISpan {
+  start: number;
+  end: number;
+  category: PIICategory;
+  value: string;
+}
+
+export interface PIIDetectionResult {
+  text: string;
+  keymap: Record<string, string>;  // "PERSON_1" → "Marie-Claire"
+}
+
+export interface AnonymizerOptions {
+  categories?: PIICategory[];
+  seedKeymap?: Record<string, string>;
+}