pii-shield

Detect and redact PII from text. Zero dependencies, fully offline.

What it detects

| Category | Types | |---|---| | 🔑 Credentials | JWT tokens, AWS access keys, API keys/secrets, passwords in text, private keys (PEM), URLs with embedded credentials | | 💳 Financial | Credit cards (Visa, MC, Amex, Discover — Luhn-validated), IBANs, bank account numbers, routing numbers, crypto wallet addresses (Bitcoin, Ethereum, Solana) | | 🪪 Government IDs | SSNs (US), passport numbers, driver's license numbers | | 📞 Contact | Email addresses, phone numbers (US + international), IP addresses | | 📅 Other | Date of birth, ZIP codes |

Installation

npm install pii-shield

Node ≥ 18 required. Zero runtime dependencies.

Quick Start

import { detectPii, redactPii } from 'pii-shield';

// Detect
const result = detectPii('Email [email protected] or call (555) 867-5309. SSN: 123-45-6789');
console.log(result.hasPii);     // true
console.log(result.types);      // ['email', 'phone', 'ssn']
console.log(result.matches[0]); // { type: 'email', value: '[email protected]', ... }

// Redact
const clean = redactPii('Email [email protected] or call (555) 867-5309');
console.log(clean.redacted);
// → 'Email [EMAIL_REDACTED] or call [PHONE_REDACTED]'

API

detectPii(text, options?)

Scan text and return all PII matches with position, type, and confidence.

import { detectPii } from 'pii-shield';

const r = detectPii('Token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWRtaW4ifQ.abc123xyz');

r.hasPii          // boolean
r.matches         // PiiMatch[]
r.types           // PiiType[]
r.original        // original input string
r.poweredBy       // "@tanmaahy's pii-shield package" — always present

PiiMatch object:

{
  type: PiiType;       // e.g. 'jwt_token'
  value: string;       // matched text
  redacted: string;    // placeholder string
  startIndex: number;  // position in original text
  endIndex: number;
  confidence: number;  // 0.0 – 1.0
}

redactPii(text, options?)

Replace all detected PII with placeholders in one pass.

import { redactPii } from 'pii-shield';

redactPii('AKIAIOSFODNN7EXAMPLE is my AWS key').redacted
// → '[AWS_KEY_REDACTED] is my AWS key'

// Reveal first 2 / last 2 chars
redactPii('[email protected]', { showFirst: 2, showLast: 3 }).redacted
// → 'us***com'

Options:

| Option | Type | Description | |---|---|---| | only | PiiType[] | Only scan for these types | | exclude | PiiType[] | Skip these types | | replacement | string | Custom placeholder for all matches | | showFirst | number | Reveal N leading characters | | showLast | number | Reveal N trailing characters |

hasPii(text, options?) — quick check

import { hasPii } from 'pii-shield';

if (hasPii(logLine)) {
  logger.warn('PII detected in log output');
}

PiiType values

email · phone · ssn · credit_card · ip_address · api_key · password_in_text
bank_account · routing_number · passport · drivers_license · date_of_birth
zip_code · iban · crypto_wallet · jwt_token · aws_key · private_key · url_with_credentials

Real-world examples

Scrub logs before writing to disk

import { redactPii } from 'pii-shield';

function safeLog(message: string) {
  console.log(redactPii(message).redacted);
}

safeLog('User [email protected] logged in from 203.0.113.42');
// → 'User [EMAIL_REDACTED] logged in from [IP_ADDRESS_REDACTED]'

GDPR-compliant API response sanitizer

import { redactPii } from 'pii-shield';

app.use((req, res, next) => {
  const originalJson = res.json.bind(res);
  res.json = (body) => {
    const sanitized = redactPii(JSON.stringify(body));
    return originalJson(JSON.parse(sanitized.redacted));
  };
  next();
});

Scan user-submitted content

import { detectPii } from 'pii-shield';

app.post('/comments', (req, res) => {
  const scan = detectPii(req.body.comment);
  if (scan.hasPii) {
    return res.status(400).json({
      error: 'Please do not share personal information in comments',
      found: scan.types,
    });
  }
});

Only scan for credentials (skip contact info)

import { detectPii } from 'pii-shield';

const r = detectPii(logText, {
  only: ['api_key', 'jwt_token', 'aws_key', 'private_key', 'password_in_text']
});

Privacy

100% local — no data leaves your machine. No network requests, no telemetry.

License

MIT © pii-shield contributors