privately

Detect, mask, and hash sensitive data (PII, secrets) in strings, objects, files, and streams.

Install

npm install privately
# or
pnpm add privately

Quick Start

import { mask, scan, hash } from 'privately';

// Mask sensitive data
mask("Contact me at [email protected]");
// → "Contact me at d*****@example.com"

// Scan for sensitive data
scan("My card is 4111-1111-1111-1111"); // → true
scan("Hello world");                     // → false

// Hash sensitive data (deterministic)
hash("Call me at 010-1234-5678");
// → "Call me at a1b2c3d4e5..."

Features

• mask — Replace sensitive data with partially-preserved masks
• scan — Detect if a string contains sensitive data (boolean)
• hash — Replace sensitive data with deterministic SHA-256 hashes
• 6 built-in patterns — Email, phone, credit card (Luhn), IP, JWT, API key
• Plugin architecture — Add custom patterns with RegExp or detect functions
• CLI — Process files and stdin streams in CI/CD pipelines
• Streaming — Line-by-line processing for large files (100MB+)

Library API

mask(input, options?)

import { mask } from 'privately';

// String masking
mask("[email protected]");              // "d*****@example.com"
mask("Call 010-1234-5678");              // "Call 010-****-5678"
mask("Card: 4111111111111111");          // "Card: ************1111"

// Object deep traversal
const user = {
  name: "Daniel",
  contact: { email: "[email protected]", phone: "010-1234-5678" }
};
mask(user);
// { name: "Daniel", contact: { email: "d*****@example.com", phone: "010-****-5678" } }

// Target specific fields
mask(user, { fields: ['contact.phone'] });

// Custom masking character
mask("[email protected]", { char: 'X' }); // "[email protected]"

scan(input)

import { scan } from 'privately';

scan("[email protected]");  // true
scan("Hello world");          // false

hash(input, algorithm?)

import { hash } from 'privately';

hash("[email protected]");               // SHA-256 hash replaces the email
hash("[email protected]", "sha512");     // SHA-512 hash

Default Import

import privately from 'privately';

privately.mask("[email protected]");
privately.scan("secret-data");
privately.hash("010-1234-5678");

Custom Patterns

import { mask } from 'privately';

// RegExp mode (simple)
const myPattern = {
  name: 'employee-id',
  pattern: /EMP-\d{6}/g,
};

mask("Employee EMP-123456 logged in", { patterns: [myPattern] });
// → "Employee ***-****** logged in"

// Function mode (advanced)
const advancedPattern = {
  name: 'custom-token',
  detect: (text) => {
    const matches = [];
    // custom detection logic
    return matches;
  },
  mask: (match) => '***REDACTED***',
};

Built-in Patterns

| Pattern | Example | Masked | |---------|---------|--------| | Email | [email protected] | d*****@example.com | | Phone | 010-1234-5678 | 010-****-5678 | | Credit Card | 4111111111111111 | ************1111 | | IPv4/IPv6 | 192.168.1.1 | 192.***.***.*** | | JWT | eyJhbG... | eyJ***... | | API Key | ghp_abc123... | ghp_***... |

CLI

# Mask a file
privately mask ./logs/app.log

# Scan for sensitive data (exit 1 if found)
privately scan ./config.json --fail-fast

# Hash sensitive data
privately hash ./data.csv --algo sha256

# Pipe from stdin
cat access.log | privately mask > sanitized.log

# JSON output
privately scan ./data.json --format json

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success (mask/hash complete, scan found nothing) | | 1 | Sensitive data found (scan) | | 2 | Error (file not found, parse failure, etc.) |

Requirements

• Node.js >= 20

License

MIT