@yellowsakura/js-pii-mask 0.8.93

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yellow Sakura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,263 @@
+# js-pii-mask
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://shields.io/badge/TypeScript-3178C6?logo=TypeScript&logoColor=FFF&style=flat-square)](https://www.typescriptlang.org)
+[![npm](https://img.shields.io/npm/v/@yellowsakura/js-pii-mask)](https://www.npmjs.com/package/@yellowsakura/js-pii-mask)
+
+<img align="left" width="100px" src="docs/logo.webp">
+
+Simple lightweight PII (Personally Identifiable Information) masking library for **TypeScript / JavaScript**.
+
+It provides **regex-based detection and masking** of common PII patterns, inspired by [OpenAI's guardrails-js](https://github.com/openai/openai-guardrails-js), with a strong focus on **simplicity, predictability, and extensibility**.
+
+> ⚠️ Heuristic-based detection: useful in practice, **not a compliance guarantee**.
+
+## Contents
+
+1. [Features](#features)
+2. [Installation and use](#installation-and-use)
+3. [Supported PII entities](#supported-pii-entities)
+4. [API reference](#api-reference)
+5. [How it works and recommended use cases](#how-it-works-and-recommended-use-cases)
+6. [Licences](#licences)
+
+## Features
+
+- 🔎 Detects **35+ common PII types** (global + regional)
+- 🧩 **Custom rules** for managing specific domains
+- ⚡ Fast, dependency-free, sequential processing
+- ❌ **Cannot**: Understand semantic context or perform deep NLP analysis
+- 🔍 **Trade-offs**: Balanced for minimal false positives, but may miss some edge cases
+
+This library is **pattern-based**.
+
+**Works well for**:
+- Structured formats (emails, credit cards, SSNs, IBANs, phone numbers)
+
+**Does NOT**:
+- Understand semantic context
+- Detect unstructured personal data
+- Perform NER or NLP
+- Guarantee 100% accuracy
+
+**Expect**:
+- False positives (numbers matching known formats)
+- False negatives (PII without clear patterns)
+
+Always combine with **manual review, access controls, encryption, and legal validation** for sensitive use cases.
+
+## Installation and use
+
+```bash
+npm install @yellowsakura/js-pii-mask
+```
+
+Quick start:
+
+For ESM:
+
+```ts
+import { mask } from '@yellowsakura/js-pii-mask'
+
+mask('Email: admin@example.com, SSN: 123-45-6789')
+// → "Email: <EMAIL_ADDRESS>, SSN: <US_SSN>"
+
+mask('Contact john@example.com or call +1-555-123-4567')
+// → "Contact <EMAIL_ADDRESS> or call +1-<PHONE_NUMBER>"
+```
+
+For CommonJS:
+
+```js
+const { mask, FixedPIIEntity } = require('@yellowsakura/js-pii-mask');
+
+mask('Email: admin@example.com, SSN: 123-45-6789')
+// → "Email: <EMAIL_ADDRESS>, SSN: <US_SSN>"
+```
+
+**Note:** all the following examples use **ESM syntax**. 
+
+### Selective fixed rule
+
+```ts
+import { mask, FixedPIIEntity } from '@yellowsakura/js-pii-mask'
+
+// Mask only specific entity types
+mask("Email: test@example.com, SSN: 123-45-6789", {
+  fixedPiiEntities: [FixedPIIEntity.EMAIL_ADDRESS]
+})
+// Output: "Email: <EMAIL_ADDRESS>, SSN: 123-45-6789"
+
+// Mask only financial information
+mask("Card: 1234-5678-9012-3456, Email: test@example.com", {
+  fixedPiiEntities: [FixedPIIEntity.CREDIT_CARD, FixedPIIEntity.US_BANK_NUMBER]
+})
+// Output: "Card: <CREDIT_CARD>, Email: test@example.com"
+```
+
+### Custom rules
+
+Use custom rules for internal or domain-specific identifiers.
+
+```ts
+import { mask } from '@yellowsakura/js-pii-mask'
+import type { CustomRule } from '@yellowsakura/js-pii-mask'
+
+const rules: CustomRule[] = [
+  { pattern: /EMP-\d{5}/g, replacement: 'EMPLOYEE_ID' },
+  { pattern: /TICKET-[A-Z0-9]{8}/gi, replacement: 'TICKET_ID' }
+]
+
+mask('Employee EMP-12345 opened TICKET-ABC12345', { customRules: rules })
+// → "Employee <EMPLOYEE_ID> opened <TICKET_ID>"
+```
+
+> Custom rules are applied **before** built-in PII detection.
+
+### Custom + fixed rules
+
+```ts
+import { mask, FixedPIIEntity } from '@yellowsakura/js-pii-mask'
+import type { CustomRule } from '@yellowsakura/js-pii-mask'
+
+mask('Employee EMP-12345 (email: john@company.com) submitted ticket', {
+  customRules: [
+    { pattern: /EMP-\d{5}/g, replacement: 'EMPLOYEE_ID' }
+  ],
+  fixedPiiEntities: [FixedPIIEntity.EMAIL_ADDRESS]
+})
+// Output: "Employee <EMPLOYEE_ID> (email: <EMAIL_ADDRESS>) submitted ticket"
+```
+
+## Supported PII entities
+
+The library includes **35+ predefined patterns**, including:
+
+### Global
+- EMAIL_ADDRESS
+- PHONE_NUMBER
+- CREDIT_CARD
+- IP_ADDRESS (IPv4 / IPv6)
+- IBAN_CODE
+- URL
+- DATE_TIME
+
+### Country-specific (examples)
+- US: SSN, Passport, Bank Number, ITIN
+- UK: NHS, NINO
+- EU: IT Fiscal Code, VAT, PESEL, NIF/NIE
+- APAC: Aadhaar, PAN, NRIC/FIN, TFN, Medicare
+
+Some entities require **context keywords** (e.g. `CVV`, `BIC_SWIFT`) to reduce false positives.
+
+For overlapping patterns, explicitly specify `fixedPiiEntities`, see [`src/pii-fixed-rules.ts`](./src/pii-fixed-rules.ts) for an exhaustive list.
+
+## API reference
+
+### `mask(text: string, options?: MaskOptions): string`
+
+Main function to mask PII in text.
+
+**Parameters:**
+- `text: string` - The text to scan and mask
+- `options?: MaskOptions` - Optional configuration object
+
+**Mask options:**
+
+```ts
+type MaskOptions = {
+  // Array of custom masking rules (always applied FIRST)
+  customRules?: CustomRule[]
+
+  // Array of specific fixed PII entities to detect (always applied AFTER custom rules)
+  // If empty or undefined, ALL fixed entities are checked
+  fixedPiiEntities?: FixedPIIEntity[]
+}
+```
+
+**Returns:** 
+- `string` - The masked text with PII replaced by `<REPLACED>` placeholders
+
+### `CustomRule` interface
+
+```ts
+interface CustomRule {
+  // Regular expression pattern to match (should use global flag /g)
+  pattern: RegExp
+  
+  // Replacement string (will be wrapped in < >)
+  replacement: string
+}
+```
+
+**Guidelines:**
+- Always use global flag (`/g`) to match all occurrences
+- Be specific to avoid matching unintended text
+- Use word boundaries (`\b`) when appropriate
+- Test thoroughly with representative data
+
+**Examples:**
+```ts
+// Good: Specific pattern with word boundaries
+{
+  pattern: /\bEMP-\d{5}\b/g,
+  replacement: 'EMPLOYEE_ID'
+}
+
+// Good: Case-insensitive matching
+{
+  pattern: /ticket-[a-z0-9]{8}/gi,
+  replacement: 'TICKET_ID'
+}
+
+// Warning: Too broad
+{
+  pattern: /\d{5}/g, // Matches any 5 digits
+  replacement: 'NUMBER'
+}
+```
+
+### `FixedPIIEntity` Enum
+
+Enumeration of all predefined PII entity types. Import to specify which entities to detect:
+
+```ts
+import { FixedPIIEntity } from '@yellowsakura/js-pii-mask'
+
+mask(text, {
+  fixedPiiEntities: [
+    FixedPIIEntity.EMAIL_ADDRESS,
+    FixedPIIEntity.PHONE_NUMBER,
+    FixedPIIEntity.US_SSN
+  ]
+})
+```
+
+## How it works and recommended use cases:
+
+1. Unicode normalization (NFKC, zero-width removal)
+2. Apply custom rules (in order)
+3. Apply fixed PII rules (all or selected)
+4. Replace matches inline
+
+Deterministic, sequential, and predictable.
+
+## Use cases
+
+✅ Test / staging data anonymization
+✅ API response redaction
+✅ Preprocessing before third-party services (e.g. LLM)
+✅ Masking internal identifiers
+
+⚠️ Use with caution for:
+- Legal, medical, or financial documents
+- Automated compliance enforcement
+
+❌ Not suitable as a standalone compliance solution.
+
+# License
+
+The code is licensed under the [MIT](https://opensource.org/licenses/MIT) by [Yellow Sakura](https://www.yellowsakura.com), [support@yellowsakura.com](mailto:support@yellowsakura.com), see the LICENSE file.  
+For more details, please refer to the [project page](https://www.yellowsakura.com/en/projects/js-pii-mask).
+
+This library is adapted from [OpenAI's guardrails-js](https://github.com/openai/openai-guardrails-js) PII detection patterns.

package/dist/index.d.mts

@@ -0,0 +1,45 @@
+import { CustomRule } from './pii-custom-rules';
+import { FixedPIIEntity } from './pii-fixed-rules';
+export type { CustomRule } from './pii-custom-rules';
+export { FixedPIIEntity } from './pii-fixed-rules';
+/**
+ * Configuration options for the `mask` function.
+ *
+ * - customRules: Optional array of custom rules for masking text patterns.
+ *   Each rule defines a regex pattern and its replacement string.
+ * - fixedPiiEntities: Optional array of predefined PII (Personally
+ *   Identifiable Information) entities to mask in the input text.
+ *
+ * Both properties are optional.
+ */
+type MaskOptions = {
+    customRules?: CustomRule[];
+    fixedPiiEntities?: FixedPIIEntity[];
+};
+/**
+ * Mask PII (Personally Identifiable Information) in text.
+ *
+ * Detects and replaces PII entities with placeholder tokens.
+ *
+ * @param text - The text to scan and mask
+ * @param options - Optional configuration object for masking rules,
+ *        see .MaskOptions
+ *
+ * @returns The text with PII entities replaced by placeholders
+ *
+ * @example
+ * // Basic usage with default fixed rules
+ * mask("Contact me at john@example.com or call 555-123-4567")
+ * // Returns: "Contact me at <EMAIL_ADDRESS> or call <PHONE_NUMBER>"
+ *
+ * @example
+ * // With custom rules
+ * mask("My name is John Doe", {
+ *   customRules: [
+ *     { pattern: /John/gi, replacement: 'FIRST_NAME' },
+ *     { pattern: /Doe/gi, replacement: 'LAST_NAME' }
+ *   ]
+ * })
+ * // Returns: "My name is <FIRST_NAME> <LAST_NAME>"
+ */
+export declare function mask(inputText: string, options?: MaskOptions): string;

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import { CustomRule } from './pii-custom-rules';
+import { FixedPIIEntity } from './pii-fixed-rules';
+export type { CustomRule } from './pii-custom-rules';
+export { FixedPIIEntity } from './pii-fixed-rules';
+/**
+ * Configuration options for the `mask` function.
+ *
+ * - customRules: Optional array of custom rules for masking text patterns.
+ *   Each rule defines a regex pattern and its replacement string.
+ * - fixedPiiEntities: Optional array of predefined PII (Personally
+ *   Identifiable Information) entities to mask in the input text.
+ *
+ * Both properties are optional.
+ */
+type MaskOptions = {
+    customRules?: CustomRule[];
+    fixedPiiEntities?: FixedPIIEntity[];
+};
+/**
+ * Mask PII (Personally Identifiable Information) in text.
+ *
+ * Detects and replaces PII entities with placeholder tokens.
+ *
+ * @param text - The text to scan and mask
+ * @param options - Optional configuration object for masking rules,
+ *        see .MaskOptions
+ *
+ * @returns The text with PII entities replaced by placeholders
+ *
+ * @example
+ * // Basic usage with default fixed rules
+ * mask("Contact me at john@example.com or call 555-123-4567")
+ * // Returns: "Contact me at <EMAIL_ADDRESS> or call <PHONE_NUMBER>"
+ *
+ * @example
+ * // With custom rules
+ * mask("My name is John Doe", {
+ *   customRules: [
+ *     { pattern: /John/gi, replacement: 'FIRST_NAME' },
+ *     { pattern: /Doe/gi, replacement: 'LAST_NAME' }
+ *   ]
+ * })
+ * // Returns: "My name is <FIRST_NAME> <LAST_NAME>"
+ */
+export declare function mask(inputText: string, options?: MaskOptions): string;

package/dist/index.js

@@ -0,0 +1 @@
+function e(e,t){if(!e||!t||t.length===0)return e;for(let n of t){if(!n.pattern||n.replacement===void 0)continue;e=e.replace(n.pattern,`<${n.replacement}>`)}return e}let t=function(e){return e.CREDIT_CARD=`CREDIT_CARD`,e.CRYPTO=`CRYPTO`,e.DATE_TIME=`DATE_TIME`,e.EMAIL_ADDRESS=`EMAIL_ADDRESS`,e.IBAN_CODE=`IBAN_CODE`,e.IP_ADDRESS=`IP_ADDRESS`,e.PHONE_NUMBER=`PHONE_NUMBER`,e.URL=`URL`,e.CVV=`CVV`,e.BIC_SWIFT=`BIC_SWIFT`,e.US_BANK_NUMBER=`US_BANK_NUMBER`,e.US_DRIVER_LICENSE=`US_DRIVER_LICENSE`,e.US_ITIN=`US_ITIN`,e.US_PASSPORT=`US_PASSPORT`,e.US_SSN=`US_SSN`,e.UK_NHS=`UK_NHS`,e.UK_NINO=`UK_NINO`,e.ES_NIF=`ES_NIF`,e.ES_NIE=`ES_NIE`,e.IT_FISCAL_CODE=`IT_FISCAL_CODE`,e.IT_DOCUMENT=`IT_DOCUMENT`,e.IT_VAT_CODE=`IT_VAT_CODE`,e.PL_PESEL=`PL_PESEL`,e.FI_PERSONAL_IDENTITY_CODE=`FI_PERSONAL_IDENTITY_CODE`,e.SG_NRIC_FIN=`SG_NRIC_FIN`,e.SG_UEN=`SG_UEN`,e.AU_ABN=`AU_ABN`,e.AU_ACN=`AU_ACN`,e.AU_TFN=`AU_TFN`,e.AU_MEDICARE=`AU_MEDICARE`,e.IN_PAN=`IN_PAN`,e.IN_AADHAAR=`IN_AADHAAR`,e.IN_VEHICLE_REGISTRATION=`IN_VEHICLE_REGISTRATION`,e.IN_VOTER=`IN_VOTER`,e.IN_PASSPORT=`IN_PASSPORT`,e.KR_RRN=`KR_RRN`,e}({});const n=[`(?:[sS][wW][iI][fF][tT])`,`(?:[bB][iI][cC])`,`(?:[bB][aA][nN][kK][\\s-]?[cC][oO][dD][eE])`,`(?:[sS][wW][iI][fF][tT][\\s-]?[cC][oO][dD][eE])`,`(?:[bB][iI][cC][\\s-]?[cC][oO][dD][eE])`].join(`|`),r=RegExp(`(?:${n})[:\\s=]+([A-Z]{4}[A-Z]{2}[A-Z0-9]{2}(?:[A-Z0-9]{3})?)\\b`,`g`),i={[t.CREDIT_CARD]:[/\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g],[t.CRYPTO]:[/\b[13][a-km-zA-HJ-NP-Z1-9]{25,34}\b/g],[t.DATE_TIME]:[/\b(0[1-9]|1[0-2])[/-](0[1-9]|[12]\d|3[01])[/-](19|20)\d{2}\b/g],[t.EMAIL_ADDRESS]:[/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,RegExp(`(?<=[?&=/])[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}`,`g`)],[t.IBAN_CODE]:[/\b[A-Z]{2}[0-9]{2}[A-Z0-9]{4}[0-9]{7}([A-Z0-9]?){0,16}\b/g],[t.IP_ADDRESS]:[/\b(?:[0-9]{1,3}\.){3}[0-9]{1,3}\b/g,/\b(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}\b/g,/\b(?:[0-9a-fA-F]{1,4}:){1,7}:|:(?::[0-9a-fA-F]{1,4}){1,7}\b/g],[t.PHONE_NUMBER]:[/\b(\+\d{1,3}[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g],[t.URL]:[/\bhttps?:\/\/(?:[-\w.])+(?::[0-9]+)?(?:\/(?:[\w/_.])*(?:\?(?:[\w&=%.])*)?(?:#(?:[\w.])*)?)?/g],[t.CVV]:[/\b(?:cvv|cvc|security\s*code|card\s*code)[\s:=]*[0-9]{3,4}\b/gi],[t.BIC_SWIFT]:[r],[t.US_BANK_NUMBER]:[/\b\d{8,17}\b/g],[t.US_DRIVER_LICENSE]:[/\b[A-Z]\d{7}\b/g],[t.US_ITIN]:[/\b9\d{2}-\d{2}-\d{4}\b/g],[t.US_PASSPORT]:[/\b[A-Z]\d{8}\b/g],[t.US_SSN]:[/\b\d{3}-\d{2}-\d{4}\b|\b\d{9}\b/g],[t.UK_NHS]:[/\b\d{3} \d{3} \d{4}\b/g],[t.UK_NINO]:[/\b[A-Z]{2}\d{6}[A-Z]\b/g],[t.ES_NIF]:[/\b\d{8}[A-Z]\b/g],[t.ES_NIE]:[/\b[XYZ]\d{7}[A-Z]\b/g],[t.IT_FISCAL_CODE]:[/\b[A-Z]{6}\d{2}[A-Z]\d{2}[A-Z]\d{3}[A-Z]\b/g],[t.IT_DOCUMENT]:[/\b[A-Z]{2}\d{7}\b/g],[t.IT_VAT_CODE]:[/\bIT\d{11}\b/g],[t.PL_PESEL]:[/\b\d{11}\b/g],[t.FI_PERSONAL_IDENTITY_CODE]:[/\b\d{6}[+-A]\d{3}[A-Z0-9]\b/g],[t.SG_NRIC_FIN]:[/\b[A-Z]\d{7}[A-Z]\b/g],[t.SG_UEN]:[/\b\d{8}[A-Z]\b|\b\d{9}[A-Z]\b/g],[t.AU_ABN]:[/\b\d{2} \d{3} \d{3} \d{3}\b/g],[t.AU_ACN]:[/\b\d{3} \d{3} \d{3}\b/g],[t.AU_TFN]:[/\b\d{9}\b/g],[t.AU_MEDICARE]:[/\b\d{4} \d{5} \d{1}\b/g],[t.IN_PAN]:[/\b[A-Z]{5}\d{4}[A-Z]\b/g],[t.IN_AADHAAR]:[/\b\d{4} \d{4} \d{4}\b/g],[t.IN_VEHICLE_REGISTRATION]:[/\b[A-Z]{2}\d{2}[A-Z]{2}\d{4}\b/g],[t.IN_VOTER]:[/\b[A-Z]{3}\d{7}\b/g],[t.IN_PASSPORT]:[/\b[A-Z]\d{7}\b/g],[t.KR_RRN]:[/\b\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])-[1-4]\d{6}\b/g]};function a(e,n=Object.values(t)){if(!e)return e;for(let t of n){let n=i[t];if(!n||!n.length)continue;for(let r of n)e=e.replace(r,`<${t}>`)}return e}function o(e){if(!e)return e;let t=/(?:\u200B|\u200C|\u200D|\u2060|\uFEFF)/g;try{return e.normalize(`NFKC`).replace(t,``)}catch{return e.replace(t,``)}}function s(t,n){let{customRules:r=[],fixedPiiEntities:i=[]}=n||{},s=o(t);return r.length>0&&(s=e(s,r)),i.length>0?a(s,i):a(s)}exports.FixedPIIEntity=t,exports.mask=s;

package/dist/index.mjs

@@ -0,0 +1 @@
+function e(e,t){if(!e||!t||t.length===0)return e;for(let n of t){if(!n.pattern||n.replacement===void 0)continue;e=e.replace(n.pattern,`<${n.replacement}>`)}return e}let t=function(e){return e.CREDIT_CARD=`CREDIT_CARD`,e.CRYPTO=`CRYPTO`,e.DATE_TIME=`DATE_TIME`,e.EMAIL_ADDRESS=`EMAIL_ADDRESS`,e.IBAN_CODE=`IBAN_CODE`,e.IP_ADDRESS=`IP_ADDRESS`,e.PHONE_NUMBER=`PHONE_NUMBER`,e.URL=`URL`,e.CVV=`CVV`,e.BIC_SWIFT=`BIC_SWIFT`,e.US_BANK_NUMBER=`US_BANK_NUMBER`,e.US_DRIVER_LICENSE=`US_DRIVER_LICENSE`,e.US_ITIN=`US_ITIN`,e.US_PASSPORT=`US_PASSPORT`,e.US_SSN=`US_SSN`,e.UK_NHS=`UK_NHS`,e.UK_NINO=`UK_NINO`,e.ES_NIF=`ES_NIF`,e.ES_NIE=`ES_NIE`,e.IT_FISCAL_CODE=`IT_FISCAL_CODE`,e.IT_DOCUMENT=`IT_DOCUMENT`,e.IT_VAT_CODE=`IT_VAT_CODE`,e.PL_PESEL=`PL_PESEL`,e.FI_PERSONAL_IDENTITY_CODE=`FI_PERSONAL_IDENTITY_CODE`,e.SG_NRIC_FIN=`SG_NRIC_FIN`,e.SG_UEN=`SG_UEN`,e.AU_ABN=`AU_ABN`,e.AU_ACN=`AU_ACN`,e.AU_TFN=`AU_TFN`,e.AU_MEDICARE=`AU_MEDICARE`,e.IN_PAN=`IN_PAN`,e.IN_AADHAAR=`IN_AADHAAR`,e.IN_VEHICLE_REGISTRATION=`IN_VEHICLE_REGISTRATION`,e.IN_VOTER=`IN_VOTER`,e.IN_PASSPORT=`IN_PASSPORT`,e.KR_RRN=`KR_RRN`,e}({});const n=[`(?:[sS][wW][iI][fF][tT])`,`(?:[bB][iI][cC])`,`(?:[bB][aA][nN][kK][\\s-]?[cC][oO][dD][eE])`,`(?:[sS][wW][iI][fF][tT][\\s-]?[cC][oO][dD][eE])`,`(?:[bB][iI][cC][\\s-]?[cC][oO][dD][eE])`].join(`|`),r=RegExp(`(?:${n})[:\\s=]+([A-Z]{4}[A-Z]{2}[A-Z0-9]{2}(?:[A-Z0-9]{3})?)\\b`,`g`),i={[t.CREDIT_CARD]:[/\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g],[t.CRYPTO]:[/\b[13][a-km-zA-HJ-NP-Z1-9]{25,34}\b/g],[t.DATE_TIME]:[/\b(0[1-9]|1[0-2])[/-](0[1-9]|[12]\d|3[01])[/-](19|20)\d{2}\b/g],[t.EMAIL_ADDRESS]:[/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,RegExp(`(?<=[?&=/])[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}`,`g`)],[t.IBAN_CODE]:[/\b[A-Z]{2}[0-9]{2}[A-Z0-9]{4}[0-9]{7}([A-Z0-9]?){0,16}\b/g],[t.IP_ADDRESS]:[/\b(?:[0-9]{1,3}\.){3}[0-9]{1,3}\b/g,/\b(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}\b/g,/\b(?:[0-9a-fA-F]{1,4}:){1,7}:|:(?::[0-9a-fA-F]{1,4}){1,7}\b/g],[t.PHONE_NUMBER]:[/\b(\+\d{1,3}[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g],[t.URL]:[/\bhttps?:\/\/(?:[-\w.])+(?::[0-9]+)?(?:\/(?:[\w/_.])*(?:\?(?:[\w&=%.])*)?(?:#(?:[\w.])*)?)?/g],[t.CVV]:[/\b(?:cvv|cvc|security\s*code|card\s*code)[\s:=]*[0-9]{3,4}\b/gi],[t.BIC_SWIFT]:[r],[t.US_BANK_NUMBER]:[/\b\d{8,17}\b/g],[t.US_DRIVER_LICENSE]:[/\b[A-Z]\d{7}\b/g],[t.US_ITIN]:[/\b9\d{2}-\d{2}-\d{4}\b/g],[t.US_PASSPORT]:[/\b[A-Z]\d{8}\b/g],[t.US_SSN]:[/\b\d{3}-\d{2}-\d{4}\b|\b\d{9}\b/g],[t.UK_NHS]:[/\b\d{3} \d{3} \d{4}\b/g],[t.UK_NINO]:[/\b[A-Z]{2}\d{6}[A-Z]\b/g],[t.ES_NIF]:[/\b\d{8}[A-Z]\b/g],[t.ES_NIE]:[/\b[XYZ]\d{7}[A-Z]\b/g],[t.IT_FISCAL_CODE]:[/\b[A-Z]{6}\d{2}[A-Z]\d{2}[A-Z]\d{3}[A-Z]\b/g],[t.IT_DOCUMENT]:[/\b[A-Z]{2}\d{7}\b/g],[t.IT_VAT_CODE]:[/\bIT\d{11}\b/g],[t.PL_PESEL]:[/\b\d{11}\b/g],[t.FI_PERSONAL_IDENTITY_CODE]:[/\b\d{6}[+-A]\d{3}[A-Z0-9]\b/g],[t.SG_NRIC_FIN]:[/\b[A-Z]\d{7}[A-Z]\b/g],[t.SG_UEN]:[/\b\d{8}[A-Z]\b|\b\d{9}[A-Z]\b/g],[t.AU_ABN]:[/\b\d{2} \d{3} \d{3} \d{3}\b/g],[t.AU_ACN]:[/\b\d{3} \d{3} \d{3}\b/g],[t.AU_TFN]:[/\b\d{9}\b/g],[t.AU_MEDICARE]:[/\b\d{4} \d{5} \d{1}\b/g],[t.IN_PAN]:[/\b[A-Z]{5}\d{4}[A-Z]\b/g],[t.IN_AADHAAR]:[/\b\d{4} \d{4} \d{4}\b/g],[t.IN_VEHICLE_REGISTRATION]:[/\b[A-Z]{2}\d{2}[A-Z]{2}\d{4}\b/g],[t.IN_VOTER]:[/\b[A-Z]{3}\d{7}\b/g],[t.IN_PASSPORT]:[/\b[A-Z]\d{7}\b/g],[t.KR_RRN]:[/\b\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])-[1-4]\d{6}\b/g]};function a(e,n=Object.values(t)){if(!e)return e;for(let t of n){let n=i[t];if(!n||!n.length)continue;for(let r of n)e=e.replace(r,`<${t}>`)}return e}function o(e){if(!e)return e;let t=/(?:\u200B|\u200C|\u200D|\u2060|\uFEFF)/g;try{return e.normalize(`NFKC`).replace(t,``)}catch{return e.replace(t,``)}}function s(t,n){let{customRules:r=[],fixedPiiEntities:i=[]}=n||{},s=o(t);return r.length>0&&(s=e(s,r)),i.length>0?a(s,i):a(s)}export{t as FixedPIIEntity,s as mask};

package/dist/pii-custom-rules.d.mts

@@ -0,0 +1,56 @@
+/**
+ * PII Custom Rules Engine
+ *
+ * This module provides a simple mechanism for applying user-defined masking rules
+ * to text content. Unlike fixed rules, custom rules are provided at runtime and
+ * allow users to mask domain-specific or organization-specific sensitive data.
+ */
+/**
+ * Custom masking rule defined by the user.
+ *
+ * A custom rule consists of a regex pattern to match and a replacement string.
+ * The pattern should use the global flag (`g`) to match all occurrences.
+ */
+export interface CustomRule {
+    pattern: RegExp;
+    replacement: string;
+}
+/**
+ * Apply custom masking rules to text.
+ *
+ * Rules are processed sequentially in the order they appear in the array.
+ * Each rule's pattern is matched against the text, and all matches are
+ * replaced with the corresponding replacement string.
+ *
+ * Processing Behavior
+ *
+ * - Sequential: Rules are applied one after another
+ * - Stateful: Later rules operate on text modified by earlier rules
+ * - No validation: Patterns are used as-is without checking
+ * - No overlap handling: First match wins
+ *
+ * @param text - The text to scan and mask
+ * @param rules - Array of custom masking rules to apply
+ *
+ * @returns The text with all custom rules applied
+ *
+ * @example
+ * // Basic usage
+ * const text = "Employee EMP-12345 logged in"
+ * const rules: CustomRule[] = [
+ *   { pattern: /EMP-\d{5}/g, replacement: 'EMPLOYEE_ID' }
+ * ]
+ * applyCustomRules(text, rules)
+ * // Returns: "Employee <EMPLOYEE_ID> logged in"
+ *
+ * @example
+ * // Multiple rules
+ * const text2 = "Ticket T-123 assigned to EMP-99999"
+ * const rules2: CustomRule[] = [
+ *   { pattern: /T-\d{3}/g, replacement: 'TICKET_ID' },
+ *   { pattern: /EMP-\d{5}/g, replacement: 'EMPLOYEE_ID' }
+ * ]
+ * applyCustomRules(text2, rules2)
+ * // Returns: "Ticket <TICKET_ID> assigned to <EMPLOYEE_ID>"
+ */
+export declare function applyCustomRules(text: string, rules: CustomRule[]): string;

package/dist/pii-custom-rules.d.ts

@@ -0,0 +1,56 @@
+/**
+ * PII Custom Rules Engine
+ *
+ * This module provides a simple mechanism for applying user-defined masking rules
+ * to text content. Unlike fixed rules, custom rules are provided at runtime and
+ * allow users to mask domain-specific or organization-specific sensitive data.
+ */
+/**
+ * Custom masking rule defined by the user.
+ *
+ * A custom rule consists of a regex pattern to match and a replacement string.
+ * The pattern should use the global flag (`g`) to match all occurrences.
+ */
+export interface CustomRule {
+    pattern: RegExp;
+    replacement: string;
+}
+/**
+ * Apply custom masking rules to text.
+ *
+ * Rules are processed sequentially in the order they appear in the array.
+ * Each rule's pattern is matched against the text, and all matches are
+ * replaced with the corresponding replacement string.
+ *
+ * Processing Behavior
+ *
+ * - Sequential: Rules are applied one after another
+ * - Stateful: Later rules operate on text modified by earlier rules
+ * - No validation: Patterns are used as-is without checking
+ * - No overlap handling: First match wins
+ *
+ * @param text - The text to scan and mask
+ * @param rules - Array of custom masking rules to apply
+ *
+ * @returns The text with all custom rules applied
+ *
+ * @example
+ * // Basic usage
+ * const text = "Employee EMP-12345 logged in"
+ * const rules: CustomRule[] = [
+ *   { pattern: /EMP-\d{5}/g, replacement: 'EMPLOYEE_ID' }
+ * ]
+ * applyCustomRules(text, rules)
+ * // Returns: "Employee <EMPLOYEE_ID> logged in"
+ *
+ * @example
+ * // Multiple rules
+ * const text2 = "Ticket T-123 assigned to EMP-99999"
+ * const rules2: CustomRule[] = [
+ *   { pattern: /T-\d{3}/g, replacement: 'TICKET_ID' },
+ *   { pattern: /EMP-\d{5}/g, replacement: 'EMPLOYEE_ID' }
+ * ]
+ * applyCustomRules(text2, rules2)
+ * // Returns: "Ticket <TICKET_ID> assigned to <EMPLOYEE_ID>"
+ */
+export declare function applyCustomRules(text: string, rules: CustomRule[]): string;

package/dist/pii-fixed-rules.d.mts

@@ -0,0 +1,121 @@
+/**
+ * PII Detection and Masking - Fixed Rules Engine
+ *
+ * This module provides a simplified PII detection system based on fixed regex patterns.
+ * It is adapted from OpenAI's guardrails-js project with significant simplifications.
+ *
+ * Original Source:
+ * https://github.com/openai/openai-guardrails-js/blob/main/src/checks/pii.ts
+ *
+ * Key differences from original:
+ *
+ * 1. Simplified Architecture: Removed guardrail system infrastructure, blocking/tripwire
+ *    functionality, and encoded PII detection (base64, hex, URL encoding)
+ *
+ * 2. Sequential Processing: Removed complex overlap detection and span deduplication.
+ *    Entities are now processed sequentially, first match wins.
+ *    This heuristic makes behavior more predictable but requires careful ordering of entity
+ *    types when overlap is possible.
+ *
+ * 3. No Capture Groups: Removed group-based pattern matching (previously used for CVV
+ *    and BIC_SWIFT). All patterns now match the entire entity directly.
+ *
+ * 4. Pure Masking Focus: Designed exclusively for text masking operations, not for
+ *    validation or blocking.
+ *
+ * This is a "fixed rules engine", patterns are predefined and well-tested. Users who need
+ * flexibility should use custom rules rather than modifying these patterns.
+ *
+ * License:
+ *
+ * The original OpenAI guardrails-js project is licensed under the MIT License.
+ * Copyright (c) OpenAI
+ *
+ * This adapted version maintains the same MIT License.
+ *
+ * @see https://github.com/openai/openai-guardrails-js
+ */
+/**
+ * Supported PII entity types for detection.
+ *
+ * These represent common personally identifiable information patterns across
+ * different regions and use cases. Each entity type maps to one or more regex
+ * patterns optimized for that specific format.
+ */
+export declare enum FixedPIIEntity {
+    CREDIT_CARD = "CREDIT_CARD",
+    CRYPTO = "CRYPTO",
+    DATE_TIME = "DATE_TIME",
+    EMAIL_ADDRESS = "EMAIL_ADDRESS",
+    IBAN_CODE = "IBAN_CODE",
+    IP_ADDRESS = "IP_ADDRESS",
+    PHONE_NUMBER = "PHONE_NUMBER",
+    URL = "URL",
+    CVV = "CVV",
+    BIC_SWIFT = "BIC_SWIFT",
+    US_BANK_NUMBER = "US_BANK_NUMBER",
+    US_DRIVER_LICENSE = "US_DRIVER_LICENSE",
+    US_ITIN = "US_ITIN",
+    US_PASSPORT = "US_PASSPORT",
+    US_SSN = "US_SSN",
+    UK_NHS = "UK_NHS",
+    UK_NINO = "UK_NINO",
+    ES_NIF = "ES_NIF",
+    ES_NIE = "ES_NIE",
+    IT_FISCAL_CODE = "IT_FISCAL_CODE",
+    IT_DOCUMENT = "IT_DOCUMENT",
+    IT_VAT_CODE = "IT_VAT_CODE",
+    PL_PESEL = "PL_PESEL",
+    FI_PERSONAL_IDENTITY_CODE = "FI_PERSONAL_IDENTITY_CODE",
+    SG_NRIC_FIN = "SG_NRIC_FIN",
+    SG_UEN = "SG_UEN",
+    AU_ABN = "AU_ABN",
+    AU_ACN = "AU_ACN",
+    AU_TFN = "AU_TFN",
+    AU_MEDICARE = "AU_MEDICARE",
+    IN_PAN = "IN_PAN",
+    IN_AADHAAR = "IN_AADHAAR",
+    IN_VEHICLE_REGISTRATION = "IN_VEHICLE_REGISTRATION",
+    IN_VOTER = "IN_VOTER",
+    IN_PASSPORT = "IN_PASSPORT",
+    KR_RRN = "KR_RRN"
+}
+/**
+ * Apply fixed PII masking rules to text
+ *
+ * This function uses a sequential, non-overlapping approach:
+ *
+ * 1. Entities are processed in the order provided
+ * 2. Once text is masked, it won't be re-matched by subsequent patterns
+ * 3. No overlap detection or resolution is performed
+ *
+ * This design prioritizes predictability and performance over handling edge cases.
+ *
+ * If patterns might overlap (e.g., CREDIT_CARD vs US_BANK_NUMBER), place the
+ * more specific pattern first in the entities array to ensure it takes precedence.
+ *
+ * @param text - The text to scan and mask
+ * @param entities - List of PII entity types to detect
+ *
+ * @returns The text with PII entities replaced
+ *
+ * @example
+ * // Default behavior
+ * applyFixedRules("Email: test@example.com")
+ * // Returns: "Email: <EMAIL_ADDRESS>"
+ *
+ * // Specific entities only
+ * applyFixedRules(
+ *   "Email: test@example.com, SSN: 123-45-6789",
+ *   [FixedPIIEntity.EMAIL_ADDRESS]
+ * )
+ * // Returns: "Email: <EMAIL_ADDRESS>, SSN: 123-45-6789"
+ *
+ * // Priority ordering matters
+ * applyFixedRules(
+ *   "1234567890123456",
+ *   [FixedPIIEntity.CREDIT_CARD, FixedPIIEntity.US_BANK_NUMBER]  // Credit card checked first
+ * )
+ * // Returns: "<CREDIT_CARD>"
+ */
+export declare function applyFixedRules(text: string, entities?: FixedPIIEntity[]): string;

package/dist/pii-fixed-rules.d.ts

@@ -0,0 +1,121 @@
+/**
+ * PII Detection and Masking - Fixed Rules Engine
+ *
+ * This module provides a simplified PII detection system based on fixed regex patterns.
+ * It is adapted from OpenAI's guardrails-js project with significant simplifications.
+ *
+ * Original Source:
+ * https://github.com/openai/openai-guardrails-js/blob/main/src/checks/pii.ts
+ *
+ * Key differences from original:
+ *
+ * 1. Simplified Architecture: Removed guardrail system infrastructure, blocking/tripwire
+ *    functionality, and encoded PII detection (base64, hex, URL encoding)
+ *
+ * 2. Sequential Processing: Removed complex overlap detection and span deduplication.
+ *    Entities are now processed sequentially, first match wins.
+ *    This heuristic makes behavior more predictable but requires careful ordering of entity
+ *    types when overlap is possible.
+ *
+ * 3. No Capture Groups: Removed group-based pattern matching (previously used for CVV
+ *    and BIC_SWIFT). All patterns now match the entire entity directly.
+ *
+ * 4. Pure Masking Focus: Designed exclusively for text masking operations, not for
+ *    validation or blocking.
+ *
+ * This is a "fixed rules engine", patterns are predefined and well-tested. Users who need
+ * flexibility should use custom rules rather than modifying these patterns.
+ *
+ * License:
+ *
+ * The original OpenAI guardrails-js project is licensed under the MIT License.
+ * Copyright (c) OpenAI
+ *
+ * This adapted version maintains the same MIT License.
+ *
+ * @see https://github.com/openai/openai-guardrails-js
+ */
+/**
+ * Supported PII entity types for detection.
+ *
+ * These represent common personally identifiable information patterns across
+ * different regions and use cases. Each entity type maps to one or more regex
+ * patterns optimized for that specific format.
+ */
+export declare enum FixedPIIEntity {
+    CREDIT_CARD = "CREDIT_CARD",
+    CRYPTO = "CRYPTO",
+    DATE_TIME = "DATE_TIME",
+    EMAIL_ADDRESS = "EMAIL_ADDRESS",
+    IBAN_CODE = "IBAN_CODE",
+    IP_ADDRESS = "IP_ADDRESS",
+    PHONE_NUMBER = "PHONE_NUMBER",
+    URL = "URL",
+    CVV = "CVV",
+    BIC_SWIFT = "BIC_SWIFT",
+    US_BANK_NUMBER = "US_BANK_NUMBER",
+    US_DRIVER_LICENSE = "US_DRIVER_LICENSE",
+    US_ITIN = "US_ITIN",
+    US_PASSPORT = "US_PASSPORT",
+    US_SSN = "US_SSN",
+    UK_NHS = "UK_NHS",
+    UK_NINO = "UK_NINO",
+    ES_NIF = "ES_NIF",
+    ES_NIE = "ES_NIE",
+    IT_FISCAL_CODE = "IT_FISCAL_CODE",
+    IT_DOCUMENT = "IT_DOCUMENT",
+    IT_VAT_CODE = "IT_VAT_CODE",
+    PL_PESEL = "PL_PESEL",
+    FI_PERSONAL_IDENTITY_CODE = "FI_PERSONAL_IDENTITY_CODE",
+    SG_NRIC_FIN = "SG_NRIC_FIN",
+    SG_UEN = "SG_UEN",
+    AU_ABN = "AU_ABN",
+    AU_ACN = "AU_ACN",
+    AU_TFN = "AU_TFN",
+    AU_MEDICARE = "AU_MEDICARE",
+    IN_PAN = "IN_PAN",
+    IN_AADHAAR = "IN_AADHAAR",
+    IN_VEHICLE_REGISTRATION = "IN_VEHICLE_REGISTRATION",
+    IN_VOTER = "IN_VOTER",
+    IN_PASSPORT = "IN_PASSPORT",
+    KR_RRN = "KR_RRN"
+}
+/**
+ * Apply fixed PII masking rules to text
+ *
+ * This function uses a sequential, non-overlapping approach:
+ *
+ * 1. Entities are processed in the order provided
+ * 2. Once text is masked, it won't be re-matched by subsequent patterns
+ * 3. No overlap detection or resolution is performed
+ *
+ * This design prioritizes predictability and performance over handling edge cases.
+ *
+ * If patterns might overlap (e.g., CREDIT_CARD vs US_BANK_NUMBER), place the
+ * more specific pattern first in the entities array to ensure it takes precedence.
+ *
+ * @param text - The text to scan and mask
+ * @param entities - List of PII entity types to detect
+ *
+ * @returns The text with PII entities replaced
+ *
+ * @example
+ * // Default behavior
+ * applyFixedRules("Email: test@example.com")
+ * // Returns: "Email: <EMAIL_ADDRESS>"
+ *
+ * // Specific entities only
+ * applyFixedRules(
+ *   "Email: test@example.com, SSN: 123-45-6789",
+ *   [FixedPIIEntity.EMAIL_ADDRESS]
+ * )
+ * // Returns: "Email: <EMAIL_ADDRESS>, SSN: 123-45-6789"
+ *
+ * // Priority ordering matters
+ * applyFixedRules(
+ *   "1234567890123456",
+ *   [FixedPIIEntity.CREDIT_CARD, FixedPIIEntity.US_BANK_NUMBER]  // Credit card checked first
+ * )
+ * // Returns: "<CREDIT_CARD>"
+ */
+export declare function applyFixedRules(text: string, entities?: FixedPIIEntity[]): string;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@yellowsakura/js-pii-mask",
+  "version": "0.8.93",
+  "description": "Simple and effective PII data masking library for TypeScript/JavaScript",
+  "keywords": [
+    "pii",
+    "mask",
+    "masking",
+    "data-privacy",
+    "privacy",
+    "gdpr",
+    "ccpa",
+    "anonymization",
+    "typescript",
+    "personal-data",
+    "sensitive-data"
+  ],
+  "homepage": "https://github.com/YellowSakura/js-pii-mask#readme",
+  "bugs": {
+    "url": "https://github.com/YellowSakura/js-pii-mask/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YellowSakura/js-pii-mask.git"
+  },
+  "license": "MIT",
+  "author": "Yellow Sakura",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "directories": {
+    "doc": "docs",
+    "test": "test"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "quality": "eslint src *.ts",
+    "test": "jest",
+    "test:single": "jest -t"
+  },
+  "devDependencies": {
+    "@swc/jest": "^0.2.39",
+    "@types/jest": "^30.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.51.0",
+    "@typescript-eslint/parser": "^8.51.0",
+    "eslint": "^9.39.0",
+    "jest": "^30.2.0",
+    "tsdown": "^0.2.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=24.12.0"
+  },
+  "module": "./dist/index.mjs"
+}