@studio-foundation/anonymizer 0.3.0-beta.1 → 0.3.0-beta.5

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@studio-foundation/anonymizer",
-  "version": "0.3.0-beta.1",
+  "version": "0.3.0-beta.5",
   "description": "PII detection and anonymization with consistent token mapping",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
   "keywords": [
     "pii",
     "anonymization",

package/ARCHITECTURE.md

@@ -1,40 +0,0 @@
-# @studio-foundation/anonymizer
-
-Bibliothèque de détection et anonymisation de PII. Remplace les données sensibles par des tokens avant envoi au LLM, avec keymap pour restaurer les valeurs originales.
-
-## Concept
-
-`anonymize(text)` → `{ text: "Hi [PERSON_1]...", keymap: { "PERSON_1": "Marie" } }`
-`deanonymize(text, keymap)` → texte original restauré.
-
-Même valeur → même token, au sein d'un appel et entre appels si `seedKeymap` fourni.
-
-## Règles
-
-- **ZERO dépendance `@studio/*`** — bibliothèque pure, réutilisable hors de Studio
-- Stateless : `Tokenizer` créé à chaque appel (ou seedé via `seedKeymap`)
-- Détection en 2 phases : regex haute précision (email, phone, SSN, credit card) + noms via patterns de salutation (best-effort)
-- La détection de personnes est non-fatale — silencieusement skippée sur erreur
-- Les spans sont non-overlapping : premier match gagne, position marquée occupée
-
-## Fichiers clés
-
-- `index.ts` — `anonymize(text, options?)`, `deanonymize(text, keymap)`, exports publics
-- `detector.ts` — `detectPII(text)` : détection regex + noms par salutation
-- `tokenizer.ts` — `Tokenizer` : génération et résolution de tokens séquentiels
-- `types.ts` — `PIICategory`, `PIISpan`, `PIIDetectionResult`, `AnonymizerOptions`
-
-## Catégories PII
-
-`person` → `PERSON_N`, `email` → `EMAIL_N`, `phone` → `PHONE_N`,
-`ssn` → `SSN_N`, `credit_card` → `CREDIT_CARD_N`, `address` → `ADDRESS_N` (réservé)
-
-## Intégration dans Studio
-
-Utilisé par `runner/src/middleware/anonymization.ts` (`AnonymizationMiddleware`).
-Activé via `--anonymize` sur `studio run` ou `anonymize: true` dans l'agent YAML.
-Keymap persisté dans `.studio/runs/anonymization/<run-id>.keymap.json`.
-
-## Dépendances
-
-Aucune `@studio/*`. Bibliothèque autonome.

package/src/detector.ts

@@ -1,97 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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

@@ -1,63 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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>;
-}

package/tests/anonymizer.test.ts

@@ -1,88 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { anonymize, deanonymize } from '../src/index.js';
-
-describe('anonymize', () => {
-  it('replaces emails with tokens', () => {
-    const result = anonymize('Send to mc@acme.com please');
-    expect(result.text).not.toContain('mc@acme.com');
-    expect(result.text).toContain('EMAIL_1');
-    expect(result.keymap['EMAIL_1']).toBe('mc@acme.com');
-  });
-
-  it('replaces the same PII twice in one call with the same token', () => {
-    const result = anonymize('Email mc@acme.com then mc@acme.com again');
-    const emails = result.text.match(/EMAIL_\d+/g) ?? [];
-    expect(emails.every(e => e === 'EMAIL_1')).toBe(true);
-    expect(result.text.split('EMAIL_1').length - 1).toBe(2);
-  });
-
-  it('assigns different tokens to different PII of same category', () => {
-    const result = anonymize('Email mc@acme.com and other@example.com');
-    expect(result.keymap['EMAIL_1']).toBeDefined();
-    expect(result.keymap['EMAIL_2']).toBeDefined();
-    expect(result.keymap['EMAIL_1']).not.toBe(result.keymap['EMAIL_2']);
-  });
-
-  it('handles multiple categories', () => {
-    const result = anonymize('Email: mc@acme.com, Phone: 514-555-1234');
-    expect(Object.keys(result.keymap).length).toBeGreaterThanOrEqual(2);
-    expect(result.text).not.toContain('mc@acme.com');
-    expect(result.text).not.toContain('514-555-1234');
-  });
-
-  it('returns unchanged text when no PII found', () => {
-    const result = anonymize('This text has no sensitive data');
-    expect(result.text).toBe('This text has no sensitive data');
-    expect(result.keymap).toEqual({});
-  });
-
-  it('seedKeymap ensures cross-call consistency', () => {
-    // First call establishes EMAIL_1 for mc@acme.com
-    const first = anonymize('mc@acme.com');
-    // Second call with the keymap as seed
-    const second = anonymize('other@example.com and mc@acme.com', {
-      seedKeymap: first.keymap,
-    });
-    // mc@acme.com should still be EMAIL_1 (from seed)
-    expect(second.keymap['EMAIL_1']).toBe('mc@acme.com');
-    // other@example.com gets EMAIL_2
-    expect(second.keymap['EMAIL_2']).toBe('other@example.com');
-  });
-});
-
-describe('deanonymize', () => {
-  it('restores original values from keymap', () => {
-    const { text, keymap } = anonymize('Send to mc@acme.com please');
-    const restored = deanonymize(text, keymap);
-    expect(restored).toBe('Send to mc@acme.com please');
-  });
-
-  it('leaves unknown tokens unchanged', () => {
-    const result = deanonymize('Hello PERSON_99', {});
-    expect(result).toBe('Hello PERSON_99');
-  });
-
-  it('restores multiple tokens', () => {
-    const keymap = { 'EMAIL_1': 'a@b.com', 'PERSON_1': 'Alice' };
-    const restored = deanonymize('EMAIL_1 sent by PERSON_1', keymap);
-    expect(restored).toBe('a@b.com sent by Alice');
-  });
-
-  it('round-trip: anonymize then deanonymize restores original', () => {
-    const original = 'Email: mc@acme.com, Phone: 514-555-1234';
-    const { text, keymap } = anonymize(original);
-    const restored = deanonymize(text, keymap);
-    expect(restored).toBe(original);
-  });
-
-  it('deanonymizes correctly when there are more than 9 PII values of same category', () => {
-    // Build a keymap with EMAIL_1 through EMAIL_11
-    const keymap: Record<string, string> = {};
-    for (let i = 1; i <= 11; i++) {
-      keymap[`EMAIL_${i}`] = `user${i}@example.com`;
-    }
-    const text = 'EMAIL_1 EMAIL_10 EMAIL_11 EMAIL_2';
-    const restored = deanonymize(text, keymap);
-    expect(restored).toBe('user1@example.com user10@example.com user11@example.com user2@example.com');
-  });
-});

package/tests/detector.test.ts

@@ -1,47 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { detectPII } from '../src/detector.js';
-
-describe('detectPII', () => {
-  it('detects email addresses', () => {
-    const spans = detectPII('Contact mc@acme.com for info');
-    const emails = spans.filter(s => s.category === 'email');
-    expect(emails.length).toBeGreaterThan(0);
-    expect(emails[0].value).toBe('mc@acme.com');
-  });
-
-  it('detects phone numbers', () => {
-    const spans = detectPII('Call 514-555-1234 now');
-    const phones = spans.filter(s => s.category === 'phone');
-    expect(phones.length).toBeGreaterThan(0);
-  });
-
-  it('detects credit card numbers', () => {
-    const spans = detectPII('Card number: 4111111111111111');
-    const cards = spans.filter(s => s.category === 'credit_card');
-    expect(cards.length).toBeGreaterThan(0);
-  });
-
-  it('returns empty array for clean text', () => {
-    const spans = detectPII('This is a normal sentence without PII');
-    expect(spans).toEqual([]);
-  });
-
-  it('returns spans with correct position bounds', () => {
-    const text = 'Email: mc@acme.com here';
-    const spans = detectPII(text);
-    const email = spans.find(s => s.category === 'email');
-    expect(email).toBeDefined();
-    expect(text.slice(email!.start, email!.end)).toBe(email!.value);
-  });
-
-  it('does not return overlapping spans', () => {
-    const text = 'Email mc@acme.com and phone 514-555-1234';
-    const spans = detectPII(text);
-    // Verify no two spans overlap
-    for (let i = 0; i < spans.length; i++) {
-      for (let j = i + 1; j < spans.length; j++) {
-        expect(spans[i].end <= spans[j].start || spans[j].end <= spans[i].start).toBe(true);
-      }
-    }
-  });
-});

package/tests/tokenizer.test.ts

@@ -1,55 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { Tokenizer } from '../src/tokenizer.js';
-
-describe('Tokenizer', () => {
-  let tokenizer: Tokenizer;
-
-  beforeEach(() => {
-    tokenizer = new Tokenizer();
-  });
-
-  it('assigns sequential tokens per category', () => {
-    const t1 = tokenizer.tokenize('Marie-Claire', 'person');
-    const t2 = tokenizer.tokenize('Jean-François', 'person');
-    const t3 = tokenizer.tokenize('mc@acme.com', 'email');
-    expect(t1).toBe('PERSON_1');
-    expect(t2).toBe('PERSON_2');
-    expect(t3).toBe('EMAIL_1');
-  });
-
-  it('returns the same token for the same value', () => {
-    const t1 = tokenizer.tokenize('Marie-Claire', 'person');
-    const t2 = tokenizer.tokenize('Marie-Claire', 'person');
-    expect(t1).toBe(t2);
-    expect(t1).toBe('PERSON_1');
-  });
-
-  it('builds keymap correctly', () => {
-    tokenizer.tokenize('Marie-Claire', 'person');
-    tokenizer.tokenize('mc@acme.com', 'email');
-    const keymap = tokenizer.getKeymap();
-    expect(keymap).toEqual({
-      'PERSON_1': 'Marie-Claire',
-      'EMAIL_1': 'mc@acme.com',
-    });
-  });
-
-  it('handles all supported categories', () => {
-    const categories = ['person', 'email', 'phone', 'address', 'ssn', 'credit_card'] as const;
-    for (const cat of categories) {
-      const token = tokenizer.tokenize('test-value', cat);
-      expect(token).toMatch(/^[A-Z_]+_1$/);
-    }
-  });
-
-  it('loadKeymap restores state for cross-call consistency', () => {
-    // Simulate loading a pre-existing keymap
-    tokenizer.loadKeymap({ 'PERSON_1': 'Alice', 'EMAIL_1': 'alice@example.com' });
-    // New tokenization should continue from counter 1
-    const t = tokenizer.tokenize('Bob', 'person');
-    expect(t).toBe('PERSON_2');
-    // Existing value should reuse its token
-    const tAlice = tokenizer.tokenize('Alice', 'person');
-    expect(tAlice).toBe('PERSON_1');
-  });
-});

package/tsconfig.json

@@ -1,20 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "commonjs",
-    "lib": ["ES2022"],
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "moduleResolution": "node"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "tests"]
-}