no-pii

PII (Personally Identifiable Information) redaction library for Node.js with built-in CLI support.

Features

• 🔒 Secure Redaction — Replace sensitive data with placeholders
• 🔄 Reversible — Restore original data from vault when needed
• 🏷️ Named Groups — Each redacted item gets a labeled placeholder
• 📦 Presets — Built-in patterns for common PII (email, credit card, Hong Kong ID, etc.)
• 🔐 Encrypted Storage — Persist rules to OS keychain or AES-256-GCM encrypted JSON
• 🖥️ CLI Ready — Pipe data through stdin or manage rules from command line

Installation

npm install no-pii

For global CLI access:

npm install -g no-pii

Quick Start

Library Usage

import { nopii } from 'no-pii';

// Basic usage with presets
const pii = nopii({
  rules: { COMMON: true, HK: true }
});

const { safeText, vault } = pii.redact(
  'Contact me at [email protected] or 5123-4567'
);

console.log(safeText);
// Contact me at [EMAIL_1] or [HK_PHONE_1]

// Restore original data
const restored = pii.restore(safeText, vault);
console.log(restored);
// Contact me at [email protected] or 5123-4567

CLI Usage

# Redact from stdin
cat log.txt | no-pii --common --hk

# Add custom rules
no-pii --add=\"NAMES:Alice,Bob,Charlie\" --db=rules.json --key=secret123

# Use OS keychain for storage
no-pii --add=\"PROJECT:AcmeCorp\" --os --service=myapp
cat data.txt | no-pii --os --service=myapp

# List current rules
no-pii --list --db=rules.json --key=secret123

Configuration

Rules

Rules can be enabled via presets or custom patterns:

const pii = nopii({
  rules: {
    // Enable all common PII patterns
    COMMON: true,
    // Enable Hong Kong-specific patterns
    HK: true,
    // Custom keyword list (array becomes OR regex)
    INTERNAL_CODES: ['PROJ-123', 'PROJ-456', 'SECRET'],
    // Custom regex
    API_KEY: /sk-[a-zA-Z0-9]{48}/
  }
});

Built-in Presets

COMMON:

• EMAIL — RFC 5322 compliant email addresses
• CREDIT_CARD — Major card networks (Visa, Mastercard, Amex, etc.)

HK (Hong Kong):

• HK_PHONE — Local phone numbers (2/3/5/6/7/8/9 prefixes)
• HKID — Hong Kong Identity Card numbers
• HK_OCTOPUS — Octopus card numbers

Storage Options

In-Memory (default):

const pii = nopii(); // Rules not persisted

OS Keychain:

const pii = nopii({
  storage: { method: 'os', service: 'myapp' }
});
await pii.load(); // Load saved rules

Encrypted JSON File:

const pii = nopii({
  storage: {
    method: './rules.db.json',
    aes: 'your-32-char-secret-key-here!!' // 32 bytes for AES-256
  }
});
await pii.load();

API Reference

nopii(options)

Creates a new NoPii instance.

| Option | Type | Description | |--------|------|-------------| | rules | Object | Key-value pairs of rules to register | | storage | Object | Storage configuration for persistence | | verbose | boolean | Enable verbose logging (default: false) |

Instance Methods

addRule(key, value)

Add a rule dynamically. Returns Promise (resolves to instance).

await pii.addRule('EMPLOYEE_ID', /EMP-\\d{5}/);
await pii.addRule('DEPARTMENTS', ['HR', 'Engineering', 'Sales']);

list()

Returns current rules as plain object.

const rules = pii.list();
// { COMMON: true, HK: true, EMAIL: /.../ }

redact(text)

Redacts PII from input text.

Returns: { safeText: string, vault: Map }

• safeText — Text with placeholders
• vault — Map of placeholder → original_value

restore(redactedText, vault)

Restores original text from vault.

const original = pii.restore(safeText, vault);

load()

Loads rules from configured storage. Returns Promise (resolves to instance).

CLI Reference

no-pii [options]

Options:
  --add=\"KEY:VAL\"    Add rule. Use commas for multiple keywords.
  --list             List all currently registered rules
  --os               Use OS Keychain (with --service)
  --db=path.json     Use encrypted JSON file (requires --key)
  --key=str          32-character AES key for --db
  --service=name     Custom service identity (default: nopii)
  --hk               Enable Hong Kong PII presets
  --common           Enable Common PII presets
  --help, -h         Show help

CLI Examples

Redact a log file:

no-pii --common --hk < application.log > redacted.log

Build a ruleset incrementally:

# Initialize with presets
no-pii --common --db=production.json --key=$(openssl rand -base64 24)

# Add company-specific terms
no-pii --add=\"PRODUCTS:WidgetPro,MegaTool\" --db=production.json --key=...
no-pii --add=\"STAFF:jdoe,asmith\" --db=production.json --key=...

# Use the ruleset
journalctl -u myapp | no-pii --db=production.json --key=...

Team-shared rules via keychain:

# One-time setup per machine
no-pii --common --hk --os --service=team-redactor

# Everyone uses same rules
npm run logs | no-pii --os --service=team-redactor

Security Notes

• AES Key: When using encrypted JSON storage, the key must be exactly 32 bytes. The library will pad/truncate shorter/longer strings.
• Vault Handling: The vault Map contains sensitive data. Do not log or serialize it unintentionally.
• OS Keychain: Relies on cross-keychain for cross-platform keychain access (macOS Keychain, Windows Credential Locker, Linux Secret Service).

Requirements

• Node.js ≥ 18.0.0 (for native node: prefixed modules)

License

MIT © littlejustnode