https://github.com/codewithveek/pii-mask
A developer-first PII masking toolkit for TypeScript and JavaScript. Detect, mask, tokenize, and anonymize personally identifiable information across structured data, freeform text, CLI pipelines, and React UIs.
https://github.com/codewithveek/pii-mask
ai-security ai-tools pii pii-anonymization pii-detection pii-protection pii-redaction
Last synced: 7 days ago
JSON representation
A developer-first PII masking toolkit for TypeScript and JavaScript. Detect, mask, tokenize, and anonymize personally identifiable information across structured data, freeform text, CLI pipelines, and React UIs.
- Host: GitHub
- URL: https://github.com/codewithveek/pii-mask
- Owner: codewithveek
- Created: 2026-03-08T13:47:27.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-01T18:14:17.000Z (2 months ago)
- Last Synced: 2026-04-02T05:34:48.628Z (2 months ago)
- Topics: ai-security, ai-tools, pii, pii-anonymization, pii-detection, pii-protection, pii-redaction
- Language: TypeScript
- Homepage: https://pii-mask.dev
- Size: 589 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# @pii-mask
A developer-first PII masking toolkit for TypeScript and JavaScript. Detect, mask, tokenize, and anonymize personally identifiable information across structured data, freeform text, CLI pipelines, and React UIs.
## Packages
| Package | Description | Install |
| ------------------------------------- | ------------------------------------------------------------- | --------------------------- |
| [`@pii-mask/core`](./packages/core) | Zero-dependency masking engine with 31 built-in detectors | `pnpm add @pii-mask/core` |
| [`@pii-mask/cli`](./packages/cli) | File I/O adapter for CSV, JSON, JSONL, and TXT files | `pnpm add -g @pii-mask/cli` |
| [`@pii-mask/react`](./packages/react) | React bindings — ``, `usePIIMask`, `usePIIMaskTable` | `pnpm add @pii-mask/react` |
| [`@pii-mask/nlp`](./packages/nlp) | Optional NLP extension for freeform name/place detection | `pnpm add @pii-mask/nlp` |
## Quick Start
```ts
import { createMasker } from '@pii-mask/core';
const masker = createMasker({ mode: 'redact' });
// Structured data
const { result } = masker.maskObject({
name: 'John Doe',
email: 'john@example.com',
ssn: '123-45-6789',
});
// → {"name":"John Doe","email":"[REDACTED]","ssn":"[REDACTED]"}
// Freeform text
const { result: text } = masker.maskString('Contact me at john@example.com');
// → "Contact me at [REDACTED]"
// Region-scoped detection (only run detectors for specific countries)
const ngMasker = createMasker({ mode: 'mask', regions: ['NG'] });
// Detection-only (no masking)
const { detections } = masker.detectString('john@example.com');
// → ['email']
// Session for cross-call consistency (shared token map and counters)
const session = masker.createSession();
masker.maskString('john@example.com', undefined, session);
masker.maskString('john@example.com', undefined, session); // same token/label
```
## Masking Modes
| Mode | Behaviour | Reversible |
| -------------- | ------------------------------------------------------------- | ---------- |
| `mask` | Partial obscure — preserves type shape (`jo***n@example.com`) | No |
| `redact` | Full replacement with `[REDACTED]` | No |
| `pseudonymize` | Consistent labels per session (`EMAIL_1`, `SSN_2`) | No |
| `anonymize` | Same as pseudonymize — consistent labels | No |
| `tokenize` | Random token (`<>`), restorable via token map | Yes |
| `substitute` | Plausible fake value via `@faker-js/faker` | No |
## Built-in Detectors
### Contact
- `email` — Email addresses
- `phone` — Phone numbers (powered by `libphonenumber-js`, 20+ country local formats)
### Government ID
- `ssn-us` — US Social Security Numbers
- `nin-ng` — Nigerian National Identification Numbers
- `bvn-ng` — Nigerian Bank Verification Numbers
- `aadhaar-in` — Indian Aadhaar numbers
- `pan-in` — Indian PAN cards
- `said-za` — South African ID numbers
- `nin-uk` — UK National Insurance Numbers
- `nik-id` — Indonesian NIK numbers
- `cpf-br` — Brazilian CPF numbers
- `passport` — Passport numbers
- `sin-ca` — Canadian Social Insurance Numbers
### Financial
- `credit-card` — Credit/debit card numbers (Luhn-validated)
- `iban` — International Bank Account Numbers
### Network
- `ip-address` — IPv4 addresses
- `ipv6` — IPv6 addresses
- `mac-address` — Hardware MAC addresses
### Biometric
- `dob` — Dates of birth (ISO 8601 and common formats)
### Identity
- `person-name` — Person names (key-name heuristic)
- `address` — Physical addresses (key-name heuristic)
- `uuid` — UUID v1–v5
- `mongodb-objectid` — MongoDB ObjectIds (24-char hex)
- `vin` — Vehicle Identification Numbers
### Secrets
- `secret-key` — API keys, tokens, passwords (key-name heuristic)
- `jwt` — JSON Web Tokens
- `bcrypt-hash` — bcrypt password hashes
- `hex-secret` — Long hex strings (32+ chars)
- `aws-key` — AWS access key IDs (AKIA/ASIA prefix)
- `github-pat` — GitHub personal access tokens
- `platform-token` — Slack (xox\*) and Stripe (sk*/rk*) tokens
## Architecture
```
┌─────────────┐ ┌──────────────┐ ┌───────────────┐
│ @pii-mask/ │ │ @pii-mask/ │ │ @pii-mask/ │
│ cli │ │ react │ │ nlp │
└──────┬──────┘ └──────┬───────┘ └───────┬───────┘
│ │ │
└─────────────────┼────────────────────┘
│
┌──────┴──────┐
│ @pii-mask/ │
│ core │
└─────────────┘
```
All packages depend only on `core`. No circular dependencies.
## Development
```bash
# Prerequisites: Node.js >= 18, pnpm
# Install dependencies
pnpm install
# Build all packages
pnpm turbo build
# Run all tests
pnpm turbo test
# Typecheck
pnpm turbo typecheck
# Lint
pnpm turbo lint
```
> **Always use pnpm.** Never use npm or yarn — this repo uses pnpm workspaces exclusively.
## License
MIT