pii-guard-node

High-performance PII detection and anonymization for Node.js

Detect, anonymize, and assess risk of personally identifiable information (PII) in text. Built with TypeScript, zero production dependencies.

Features

• 15 Built-in Recognizers — Email, Phone, SSN, Credit Card, IBAN, Passport, Driver's License, DOB, IP, MAC, URL, AWS Keys, Crypto Wallets, VIN, Medical License
• Multiple Anonymization Strategies — Redact, Mask, Custom functions, Consistent anonymization
• Risk Assessment — Document-level risk scoring with factor analysis
• Compliance Checking — GDPR, HIPAA, PCI-DSS, CCPA, SOX
• Context-Aware Scoring — Boosts confidence when context words are nearby
• Allow/Deny Lists — Whitelist known safe values, force-detect specific terms
• Extensible — Create custom recognizers by extending BasePatternRecognizer
• Zero Dependencies — No production dependencies
• TypeScript First — Full type safety with exported types

Installation

npm install pii-guard-node

Quick Start

import { PIIGuard } from 'pii-guard-node';

const guard = new PIIGuard();

// Simple analysis
const result = await guard.analyze('Email [email protected] or call 555-123-4567');
console.log(result.results);
// [
//   { entityType: 'EMAIL_ADDRESS', text: '[email protected]', score: 0.95, ... },
//   { entityType: 'PHONE_NUMBER', text: '555-123-4567', score: 0.75, ... }
// ]

// Simple anonymization
const anon = await guard.anonymize('SSN: 123-45-6789');
console.log(anon.anonymizedText);
// "SSN: <SSN>"

// Full pipeline: analyze + anonymize + risk + compliance
const full = await guard.process('Patient John Smith, SSN 123-45-6789, email [email protected]');
console.log(full.risk?.level);       // "high"
console.log(full.compliance?.isCompliant); // false

API Reference

new PIIGuard(config?)

Create a new PIIGuard instance.

const guard = new PIIGuard({
  language: 'en',                    // Default language
  defaultThreshold: 0.5,            // Minimum confidence score
  logLevel: 'warn',                 // 'debug' | 'info' | 'warn' | 'error' | 'silent'
  riskAssessmentEnabled: true,      // Enable risk scoring
  complianceEnabled: true,          // Enable compliance checks
  complianceRegulations: ['GDPR'],  // Regulations to check
});

guard.analyze(text | request)

Detect PII entities in text.

// String shorthand
const result = await guard.analyze('Contact [email protected]');

// Full request
const result = await guard.analyze({
  text: 'Contact [email protected]',
  language: 'en',
  entities: ['EMAIL_ADDRESS', 'PHONE_NUMBER'],  // Filter entity types
  threshold: 0.6,                                // Override threshold
  allowList: ['[email protected]'],              // Ignore these values
  denyList: [{ text: 'Acme Corp', entityType: 'ORGANIZATION' }],
});

guard.anonymize(text | request)

Detect and anonymize PII in one call.

const result = await guard.anonymize('Card: 4111 1111 1111 1111');
console.log(result.anonymizedText); // "Card: <CREDIT_CARD>"
console.log(result.items);          // Array of anonymized items

guard.process(text | request)

Full pipeline — analyze, anonymize, assess risk, check compliance.

const result = await guard.process('SSN: 123-45-6789');
console.log(result.analysis);    // Detection results
console.log(result.anonymized);  // Anonymized text
console.log(result.risk);        // Risk assessment
console.log(result.compliance);  // Compliance report

Anonymization Strategies

Redact (default)

const guard = new PIIGuard({
  defaultAnonymizer: { type: 'redact', redactFormat: '<{entity_type}>' },
});
// "[email protected]" → "<EMAIL_ADDRESS>"

Mask

const guard = new PIIGuard({
  defaultAnonymizer: {
    type: 'mask',
    maskChar: '*',
    unmaskCount: 4,
    unmaskFrom: 'end',
  },
});
// "4111111111111111" → "************1111"

Custom

const guard = new PIIGuard({
  defaultAnonymizer: {
    type: 'custom',
    customFunction: (text, result) => `[REDACTED:${result.entityType}]`,
  },
});

Per-Entity Configuration

const guard = new PIIGuard({
  defaultAnonymizer: { type: 'redact' },
  entityAnonymizers: {
    CREDIT_CARD: { type: 'mask', maskChar: '*', unmaskCount: 4, unmaskFrom: 'end' },
    EMAIL_ADDRESS: { type: 'mask', maskChar: 'X' },
  },
});

Consistent Anonymization

const guard = new PIIGuard({
  consistentAnonymization: {
    enabled: true,
    format: 'numbered',  // 'numbered' | 'lettered'
    scope: 'per_request',
  },
});
// "John told John about Mary" → "<PERSON_NAME_1> told <PERSON_NAME_1> about <PERSON_NAME_2>"

Custom Recognizers

import { BasePatternRecognizer, PIIGuard } from 'pii-guard-node';

class EmployeeIDRecognizer extends BasePatternRecognizer {
  constructor() {
    super({
      name: 'EmployeeIDRecognizer',
      entityType: 'EMPLOYEE_ID',
      version: '1.0.0',
      supportedLanguages: ['*'],
      patterns: [
        {
          name: 'emp_id',
          regex: /\bEMP-\d{6}\b/,
          score: 0.9,
        },
      ],
    });
  }
}

const guard = new PIIGuard();
guard.registerRecognizer(new EmployeeIDRecognizer());

const result = await guard.analyze('Employee EMP-123456 reported in');
// Detects EMPLOYEE_ID

Risk Assessment

const result = await guard.process('John Smith, SSN 123-45-6789, card 4111111111111111');

console.log(result.risk);
// {
//   overallScore: 0.85,
//   level: 'critical',
//   factors: [
//     { name: 'critical_entities', ... },
//     { name: 'identity_combination', ... },
//     { name: 'financial_combination', ... },
//   ],
//   entityDetails: [...],
//   summary: 'Risk level: CRITICAL. Found 3 PII entities...'
// }

Compliance Checking

const guard = new PIIGuard({
  complianceEnabled: true,
  complianceRegulations: ['GDPR', 'HIPAA', 'PCI_DSS'],
});

const result = await guard.process('Patient John, SSN 123-45-6789');
console.log(result.compliance);
// {
//   isCompliant: false,
//   violations: [...],
//   regulations: [
//     { regulation: 'GDPR', compliant: false, violations: [...] },
//     { regulation: 'HIPAA', compliant: false, violations: [...] },
//     { regulation: 'PCI_DSS', compliant: true, violations: [] },
//   ]
// }

Supported Entity Types

| Entity Type | Examples | |---|---| | EMAIL_ADDRESS | [email protected] | | PHONE_NUMBER | (555) 123-4567, +1-555-123-4567 | | SSN | 123-45-6789 | | CREDIT_CARD | 4111 1111 1111 1111 | | IBAN | GB29 NWBK 6016 1331 9268 19 | | IP_ADDRESS | 192.168.1.1 | | MAC_ADDRESS | 00:1A:2B:3C:4D:5E | | URL | https://example.com | | PASSPORT | A12345678 | | DRIVERS_LICENSE | D1234567 | | DATE_OF_BIRTH | 01/15/1990 | | VIN | 1HGBH41JXMN109186 | | MEDICAL_LICENSE | NPI, DEA numbers | | AWS_KEY | AKIAIOSFODNN7EXAMPLE | | CRYPTO_WALLET | 0x742d35Cc6634..., bc1qar0srrr... |

License

MIT