no-pii 1.0.0

package/README.md

@@ -0,0 +1,208 @@
+# nopii
+
+> **No PII** — PII detection and redaction with secure vault storage
+
+[![npm version](https://img.shields.io/npm/v/nopii.svg)](https://www.npmjs.com/package/nopii)
+[![license](https://img.shields.io/npm/l/nopii.svg)](https://github.com/littlejustnode/nopii/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/nopii.svg)](https://nodejs.org/)
+
+Zero-dependency PII (Personally Identifiable Information) detection and redaction library with pluggable strategies, secure vault storage, and state persistence.
+
+## Features
+
+- 🔒 **PII Redaction** — Automatically detect and replace sensitive data with safe placeholders
+- 🗄️ **Secure Vault** — Store redacted values in an encrypted vault for later restoration
+- 🔧 **Pluggable Strategies** — Define custom regex patterns or word-based masking rules
+- 💾 **Persistent Storage** — Save/load configurations to OS keychain, encrypted JSON, or memory
+- 🚀 **Zero Dependencies** — Uses only Node.js built-in modules (except optional `cross-keychain` for OS storage)
+- 📦 **ESM Native** — Modern ES module syntax with named exports
+- 🔄 **Bidirectional** — Redact and restore text without data loss
+
+## Installation
+
+```bash
+npm install nopii
+```
+
+## Quick Start
+
+```javascript
+import { nopii } from 'nopii';
+
+// Create instance with in-memory storage
+const pii = nopii();
+
+// Add masking strategies
+await pii.addMasking('email', 'user@example.com', 'admin@company.org');
+await pii.addStrategy('ssn', /\\b\\d{3}-\\d{2}-\\d{4}\\b/g);
+
+// Redact sensitive text
+const { safeText, vault } = pii.redact(
+  'Contact user@example.com or admin@company.org. SSN: 123-45-6789'
+);
+
+console.log(safeText);
+// 'Contact _P1_ or _P2_. SSN: _P3_'
+
+// Restore original text
+const restored = pii.restore(safeText, vault);
+console.log(restored);
+// 'Contact user@example.com or admin@company.org. SSN: 123-45-6789'
+```
+
+## API Reference
+
+### `nopii(options)`
+
+Factory function to create a new NoPii instance.
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `verbose` | `boolean` | `false` | Enable verbose logging |
+| `service` | `string` | `'nopii'` | Service name for OS keychain storage |
+| `account` | `string` | `'default'` | Account name for OS keychain storage |
+| `memory` | `string\\|object` | `'memory'` | Storage backend: `'os'`, `'memory'`, or custom object |
+| `aesKey` | `string` | — | Required for encrypted JSON file storage |
+
+**Storage Backends:**
+
+- `'memory'` (default) — In-memory Map storage
+- `'os'` — OS native keychain (Windows Credential Manager, macOS Keychain, Linux Secret Service) via `cross-keychain`
+- `'./path/to/file.json'` — Encrypted JSON file storage (requires `aesKey`)
+- Custom object — Must implement `{ get(key), set(key, value) }`
+
+### `instance.addMasking(label, ...words)`
+
+Add word-based masking strategy. Escapes special regex characters automatically.
+
+```javascript
+await pii.addMasking('names', 'John Doe', 'Jane Smith');
+```
+
+### `instance.addStrategy(name, regex)`
+
+Add custom regex strategy.
+
+```javascript
+await pii.addStrategy('credit-card', /\\b\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}\\b/g);
+```
+
+### `instance.load(input)`
+
+Load configuration from file, string, or storage.
+
+```javascript
+// Load from default storage
+await pii.load();
+
+// Load from JSON file
+await pii.load('./config.json');
+
+// Load from object
+await pii.load({
+  masking: { names: ['Alice', 'Bob'] },
+  strategies: { phone: '^\\\\d{3}-\\\\d{3}-\\\\d{4}$' }
+});
+```
+
+### `instance.redact(text)`
+
+Redact PII from text. Returns `{ safeText, vault }`.
+
+```javascript
+const { safeText, vault } = pii.redact('Sensitive data here');
+// safeText: Redacted text with placeholders
+// vault: Map of placeholder → original value
+```
+
+### `instance.restore(redactedText, vault)`
+
+Restore original text from redacted version using vault.
+
+```javascript
+const original = pii.restore(safeText, vault);
+```
+
+## Configuration Persistence
+
+### OS Keychain Storage
+
+```javascript
+const pii = nopii({ memory: 'os', service: 'myapp', account: 'pii' });
+
+// Strategies are persisted automatically
+await pii.addMasking('api-keys', 'sk-abc123', 'sk-xyz789');
+
+// Load on next run
+await pii.load();
+```
+
+### Encrypted JSON Storage
+
+```javascript
+const pii = nopii({
+  memory: './secrets/pii-store.json',
+  aesKey: 'your-32-char-secret-key-here!!' // Must be 32+ chars for AES-256-GCM
+});
+
+await pii.addStrategy('token', /Bearer\\s+[a-zA-Z0-9]+/g);
+// Automatically encrypted and saved to ./secrets/pii-store.json
+```
+
+## Advanced Example
+
+```javascript
+import { nopii } from 'nopii';
+import fs from 'node:fs/promises';
+
+// Initialize with OS keychain storage
+const pii = nopii({
+  memory: 'os',
+  service: 'my-cli-tool',
+  account: 'redaction-config'
+});
+
+// Load existing configuration
+await pii.load();
+
+// Add comprehensive PII patterns
+await pii.addStrategy('email', /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}/g);
+await pii.addStrategy('phone', /\\b\\(?\\d{3}\\)?[-.\\s]?\\d{3}[-.\\s]?\\d{4}\\b/g);
+await pii.addStrategy('ip', /\\b(?:\\d{1,3}\\.){3}\\d{1,3}\\b/g);
+await pii.addMasking('internal-codes', 'PROJ-1234', 'SECRET-5678');
+
+// Process log file
+const logs = await fs.readFile('./app.log', 'utf8');
+const { safeText, vault } = pii.redact(logs);
+
+// Save redacted logs (safe for sharing)
+await fs.writeFile('./app-redacted.log', safeText);
+
+// Save vault separately (keep secure!)
+await fs.writeFile('./vault.json', JSON.stringify([...vault]));
+
+// Later: restore original
+const restored = pii.restore(safeText, new Map(JSON.parse(await fs.readFile('./vault.json', 'utf8'))));
+```
+
+## Security Considerations
+
+- **Vault Security**: The vault contains the actual PII. Store it encrypted or in a secure location.
+- **AES Key Management**: When using JSON storage, protect your `aesKey` — it decrypts the entire store.
+- **OS Keychain**: Relies on system security. On shared machines, ensure proper user isolation.
+- **Memory Storage**: Not persisted; cleared on process exit. Suitable for one-time operations.
+
+## Requirements
+
+- Node.js ≥ 18.0.0
+- For OS storage: `cross-keychain` peer dependency (auto-installed)
+
+## License
+
+MIT © [littlejustnode](https://github.com/littlejustnode)
+
+---
+
+**Note**: This package is designed for data processing pipelines, log sanitization, and GDPR/privacy compliance workflows. Always follow your organization's data handling policies when processing PII.

package/nopii.js

@@ -0,0 +1,175 @@
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+import { Buffer } from 'node:buffer';
+import { getPassword, setPassword } from 'cross-keychain';
+
+export class NoPii {
+  #strategies = [];
+  #combinedRegex = null;
+  #storage = null;
+  #config = {};
+  #currentConfig = { masking: {}, strategies: {} };
+
+  constructor(options = {}) {
+    this.#config = {
+      verbose: false,
+      service: 'nopii',
+      account: 'default',
+      ...options
+    };
+    this.#storage = this.#initStorage(this.#config.memory);
+  }
+
+  #initStorage(memoryOption) {
+    if (memoryOption && typeof memoryOption === 'object' && typeof memoryOption.get === 'function') {
+      return memoryOption;
+    }
+
+    if (memoryOption === 'os') {
+      const { service, account } = this.#config;
+      return {
+        get: async (key) => {
+          // Use underscore instead of colon for Windows compatibility
+          const val = await getPassword(service, `${account}_${key}`);
+          return val ? JSON.parse(val) : null;
+        },
+        set: async (key, val) => {
+          await setPassword(service, `${account}_${key}`, JSON.stringify(val));
+        }
+      };
+    }
+
+    if (typeof memoryOption === 'string' && memoryOption.endsWith('.json')) {
+      const aesKey = this.#config.aesKey;
+      if (!aesKey) throw new Error("nopii: aesKey required for JSON storage.");
+
+      return {
+        path: memoryOption,
+        key: Buffer.alloc(32, aesKey),
+        async get() {
+          try {
+            const raw = await fs.readFile(this.path, 'utf8');
+            return JSON.parse(this.decrypt(raw));
+          } catch (e) {
+            // Rethrow decryption/auth errors, ignore "file not found"
+            if (e.message.includes('Decryption failed')) throw e;
+            return null;
+          }
+        },
+        async set(key, val) {
+          const encrypted = this.encrypt(JSON.stringify(val));
+          await fs.writeFile(this.path, encrypted);
+        },
+        encrypt(text) {
+          const iv = crypto.randomBytes(12);
+          const cipher = crypto.createCipheriv('aes-256-gcm', this.key, iv);
+          const enc = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]);
+          return Buffer.concat([iv, cipher.getAuthTag(), enc]).toString('base64');
+        },
+        decrypt(data) {
+          try {
+            const buf = Buffer.from(data, 'base64');
+            const iv = buf.subarray(0, 12);
+            const tag = buf.subarray(12, 28);
+            const enc = buf.subarray(28);
+            const decipher = crypto.createDecipheriv('aes-256-gcm', this.key, iv);
+            decipher.setAuthTag(tag);
+            // .final() throws if the tag (GCM auth) is invalid
+            return decipher.update(enc, 'utf8') + decipher.final('utf8');
+          } catch (err) {
+            throw new Error(`Decryption failed: ${err.message}`);
+          }
+        }
+      };
+    }
+
+    const _mem = new Map();
+    return {
+      get: async (key) => _mem.get(key),
+      set: async (key, val) => _mem.set(key, val)
+    };
+  }
+
+  async load(input) {
+    let configData = null;
+    if (!input && this.#config.memory) {
+      configData = await this.#storage.get('config');
+    } else if (typeof input === 'string') {
+      const raw = input.endsWith('.json') ? await fs.readFile(input, 'utf8') : input;
+      configData = JSON.parse(raw);
+    } else {
+      configData = input;
+    }
+
+    if (configData) {
+      await this.#applyConfig(configData, false);
+    }
+    return this;
+  }
+
+  async #persist() {
+    if (this.#config.memory) {
+      await this.#storage.set('config', this.#currentConfig);
+    }
+  }
+
+  async #applyConfig(data, shouldPersist = true) {
+    if (data.masking) {
+      for (const [label, words] of Object.entries(data.masking)) {
+        await this.addMasking(label, ...words);
+      }
+    }
+    if (data.strategies) {
+      for (const [name, pattern] of Object.entries(data.strategies)) {
+        await this.addStrategy(name, new RegExp(pattern, 'u'));
+      }
+    }
+    if (shouldPersist) await this.#persist();
+  }
+
+  async addMasking(label, ...words) {
+    const pattern = words.map(w => w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+    this.#currentConfig.masking[label] = words;
+    this.#strategies.push({ name: label, regex: new RegExp(`(${pattern})`, 'u') });
+    this.#compile();
+    await this.#persist();
+    return this;
+  }
+
+  async addStrategy(name, regex) {
+    this.#currentConfig.strategies[name] = regex.source;
+    this.#strategies.push({ name, regex });
+    this.#compile();
+    await this.#persist();
+    return this;
+  }
+
+  #compile() {
+    if (this.#strategies.length === 0) return;
+    const source = this.#strategies.map(s => `(?<${s.name}>${s.regex.source})`).join('|');
+    this.#combinedRegex = new RegExp(source, 'gu');
+  }
+
+  redact(text) {
+    if (!this.#combinedRegex || !text) return { safeText: text, vault: new Map() };
+    const vault = new Map();
+    let count = 0;
+    const safeText = text.replace(this.#combinedRegex, (...args) => {
+      const groups = args.at(-1);
+      const label = Object.keys(groups).find(key => groups[key] !== undefined);
+      const placeholder = `_P${++count}_`;
+      vault.set(placeholder, groups[label]);
+      return placeholder;
+    });
+    return { safeText, vault };
+  }
+
+  restore(redactedText, vault) {
+    if (!redactedText || !vault || vault.size === 0) return redactedText;
+    const keys = Array.from(vault.keys()).sort((a, b) => b.length - a.length);
+    const restoreRegex = new RegExp(keys.map(k => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'), 'g');
+    return redactedText.replace(restoreRegex, (m) => vault.get(m));
+  }
+}
+
+export const nopii = (options) => new NoPii(options);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "no-pii",
+  "version": "1.0.0",
+  "description": "PII redaction utility with encrypted local persistence and OS keychain support.",
+  "type": "module",
+  "main": "nopii.js",
+  "files": [
+    "nopii.js",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test test.js",
+    "lint": "eslint .",
+    "example": "node examples/basic-usage.js"
+  },
+  "keywords": [
+    "nopii",
+    "pii",
+    "redaction",
+    "security",
+    "keychain",
+    "encryption",
+    "node-js",
+    "esm"
+  ],
+  "author": "littlejustnode",
+  "license": "MIT",
+  "dependencies": {
+    "cross-keychain": "^1.1.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/littlejustnode/nopii.git"
+  },
+  "bugs": {
+    "url": "https://github.com/littlejustnode/nopii/issues"
+  },
+  "homepage": "https://github.com/littlejustnode/nopii#readme"
+}